Mavenlink

Stories (Tasks)

Stories are used in Mavenlink to track productivity. This model includes tasks, deliverables, and milestones.

Story objects have the following readable attributes:

  • id - the internal story id
  • workspace_id - the internal id for the workspace of the story
  • parent_id - the internal story id of a story's parent story (only for sub-stories)
  • title - the title of the story
  • description - a user provided description of the story
  • story_type - the story's type (task, deliverable, milestone, or issue)
  • state - the current state of the story, state options are based on the story_type
    • story states for task, deliverable and milestones are not started, started, and completed
    • story states for issues are new, reopened, in progress, blocked, fixed, duplicate, can't repro, resolved, and won't fix
  • priority - the current priority (importance) of the story (low, normal, high, critical). The default is normal.
  • position - a number corresponding to the story's order relative to all other stories
  • archived - the archived status of the story (true of false)
  • deleted_at - the date the story was deleted
  • percentage_complete - the completion percentage of the story
  • updated_at - the date the story was last updated
  • created_at - the date the story was created in Mavenlink
  • due_date - the due date given to the story
  • start_date - the start date given to the story
  • sub_story_count - the number of sub-stories under this story
  • weight - an optional integer representing the weight of the story. Can only be set on a parent-level milestone. Only present for budgeted workspaces and if the authenticated user can view budget information.
  • billable - whether this story is billable time. Only present for budgeted workspaces and if the authenticated user can view budget information.
  • fixed_fee - the fixed fee status of the story (true or false). Time logged against a fixed fee story does not impact the story's budget. Only present for budgeted workspaces and if the authenticated user can view budget information.
  • budget_estimate_in_cents - the budget for the story in cents (integer). Only present if the Workspace has budgets enabled and the authenticated user can view budget information.
  • sub_stories_budget_estimate_in_cents - the budget for the sub-stories in cents (integer). Only present if the Workspace has budgets enabled and the authenticated user can view budget information.
  • budget_used_in_cents - the value of all time entries logged against this story (integer). Only present if the Workspace has budgets enabled and the authenticated user can view budget information.
  • sub_stories_budget_used_in_cents - the value of all sub-stories' time entries logged against this story (integer). Only present if the Workspace has budgets enabled and the authenticated user can view budget information.
  • time_estimate_in_minutes - the time estimate for the story in minutes (integer). Only present if the Workspace has budgets enabled and the authenticated user can view time information.
  • sub_stories_time_estimate_in_minutes - the time estimate for the sub-stories in minutes (integer). Only present if the Workspace has budgets enabled and the authenticated user can view time information.
  • logged_billable_time_in_minutes - the sum of all billable time logged against this story (integer). Only present if the Workspace has budgets enabled and the authenticated user can view time information.
  • sub_stories_billable_time_in_minutes - the sum of all sub-stories' billable time logged against this story (integer). Only present if the Workspace has budgets enabled and the authenticated user can view time information.
  • logged_nonbillable_time_in_minutes - the sum of all non-billable time logged against this story (integer). Only present if the Workspace has budgets enabled and the authenticated user can view time information.

Fetching Stories

You can access all of your own stories from all workspaces you are in through the API as follows:

curl "https://api.mavenlink.com/api/v1/stories.json"

The resulting JSON will be an array of objects. The stories will be sorted by the updated_at field in descending order by default.

If you are a reports viewer or adminstrator you can retrieve all stories on an account with the all_on_account param:

curl "https://api.mavenlink.com/api/v1/stories.json?all_on_account=true"

Associated Objects

You can include stories' associations with the include param. For example, to include returned stories' assignees and workspaces, you would do the following:

curl "https://api.mavenlink.com/api/v1/stories.json?include=assignees,workspace"

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

  • workspace - the workspace (project) that owns this story, returned in the workspaces top-level key
  • parent - when you include this association, stories that are sub-stories will have a parent_id key referencing their parent story in the stories top-level key
  • creator - when you include this association, creating user will be in the users top-level key whose id will be in the story's creator_id
  • assignees - an array of User IDs called assignee_ids that contains the users assigned to this story, returned in the users top-level key
  • sub_stories - sub-stories of this story, returned in the stories top-level key; stories will contain a sub_story_ids array
  • tags - an array of Tag IDs returned in the tags top-level key; stories will contain a tag_ids array
  • story_tasks - Returns an array of story_task_ids on each story, as well as includes the Story Tasks in the top-level story_tasks JSON key

The following associations are available on GET requests for single stories (e.g., GET /stories/5.json):

Filtering Stories

The Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain stories that meet those conditions.

  • show_archived - (default false) includes archived stories
  • show_deleted - (default false) includes stories with a deleted_at timestamp
  • show_from_archived_workspaces - (default false) include stories from Workspaces that are archived
  • story_type - only stories of a certain type
  • parents_only - do not include sub-stories
  • assigned_to_current_user - only stories that are assigned to the current user when true; or only stories not assigned to the current user, including unassigned stories, when false
  • with_parent_id - only sub-stories of the story with the given ID
  • uncompleted - only stories with state not equal to completed
  • with_start_or_due_date - only stories that have either a valid start_date or due_date or both
  • without_past_completed - excludes stories that have state as completed and have a due_date before today
  • workspace_id - only return stories from the given workspace (project)
  • starting_between - only return stories that have a start_date between the given dates. If a date is not passed in, it is interpreted as negative or positive infinity
  • due_between - only return stories that have a due_date between the given dates. If a date is not passed in, it is interpreted as negative or positive infinity
  • active_between - include stories whose range of start_date to due_date intersects with the range date range from the parameters
  • created_before - include stories created before the given timestamp (in ISO 8601 format)
  • created_after - include stories created after the given timestamp (in ISO 8601 format)
  • updated_before - include stories updated before the given timestamp (in ISO 8601 format)
  • updated_after - include stories updated after the given timestamp (in ISO 8601 format)

For example to get all stories with a start_date in the year 2000:

curl "https://api.mavenlink.com/api/v1/stories.json?starting_between=2000-01-01:2000-12-31"

Searching Stories

You can search among the stories that you have access to by passing a search param and query string:

curl "https://api.mavenlink.com/api/v1/stories.json?search=estimate%20high%20priority"

Stories are searched across the following fields:

  • title
  • workspace title
  • description
  • state
  • assignee names
  • tags

The following filters can be applied in conjunction with search:

  • show_archived
  • assigned_to_current_user
  • uncompleted
  • starting_between
  • due_between
  • active_between
  • all_on_account

While not all filters are available, ordering is always by relevancy, and only requests do not apply to search, pagination and includes continue to work as usual.

Ordering Stories

Valid orders are:

  • updated_at
  • created_at
  • importance - orders stories based on their state, start_date and due_date. Stories that are not_started and past their start_date are more important than stories that are started and past their due_date, which are more important than started stories that are between their start_date and due_date.
  • position - orders stories based on their position, which is accessible to users as draggable stories in Project Tracker. Because position is relative, this ordering only well defined when using filters workspace_id and parents_only (parent stories within a workspace) or with_parent_id (sub-stories of a specific parent story).

The default order is updated_at:desc.

Getting a Single Story

As with all resources, you can request either GET /api/v1/stories.json?only=5 or GET /api/v1/stories/5.json. In both cases, default filters will be applied. Therefore, you won't receive archived or deleted Story objects, or Story objects in archived Workspaces, and will receive a 404 status on the "show" route, unless you provide the show_archived:true, show_deleted:true, and show_from_archived_workspaces:true filters, respectively.

Creating a New Story

Mavenlink Stories belong to a workspace (project) and take the following parameters:

  • title - (required) the title of the story - max 200 characters
  • story_type - (required) the type of the story: task, deliverable, or milestone
  • workspace_id - (required) the ID of the Workspace in which the story will be created
  • description - (optional) a description of the new story - max 1000 characters
  • parent_id - (optional) represents the parent of this story, making this a sub-story
  • start_date - (optional) the date the story should be started; format should look like YYYY-MM-DD
  • archived - (optional) the archived status of the story (true or false)
  • due_date - (optional) the date the story is due; format should look like YYYY-MM-DD
  • assignee_ids - (optional) an array of User IDs that the new story should be assigned to
  • budget_estimate_in_cents - (optional) the budget in cents of the new story (integer). This is only valid in budgeted Workspaces and if the user can view budget information
  • time_estimate_in_minutes - (optional) the time estimate in minutes of the new story (integer). This is only valid in budgeted Workspaces and if the user can view budget information
  • fixed_fee - (optional) the fixed fee status of the story (true or false). Time logged against a fixed fee story does not impact the story's budget. Only present for budgeted workspaces and if the authenticated user can view budget information.
  • billable - (optional) whether this story is billable time. Only present for budgeted workspaces and if the authenticated user can view budget information.
  • tag_list - (optional) a comma separated String of tags
  • checklist - (optional) an array of strings. Each string will become a separate checklist item.
  • percentage_complete - (optional) the completion percentage of the story; setting above 0 starts the story and setting to 100 completes the story.

You can create stories as follows:

curl -d "story[title]=My Story Title" -d "story[workspace_id]=10" -d "story[story_type]=task" "https://api.mavenlink.com/api/v1/stories.json"

Creating Multiple New Stories

You may create many Story objects at once if you submit a stories array instead of a single story value. An example would be to send a request with the following parameters encoded as application/json:

{"stories"=>[{"title"=>"Task1", "workspace_id"=>"10", "story_type"=>"task"}, {"title"=>"Task2", "workspace_id"=>"20", "story_type"=>"task"}]}

Using curl, that request could be sent as:

curl -H "Content-Type: application/json" -d '{"stories":[{"workspace_id":"10","title":"Task1","story_type":"task"},{"workspace_id":"20","title":"Task2","story_type":"task"}]}' "https://api.mavenlink.com/api/v1/stories.json"

When making requests with the checklist parameter encode the values as an array, see example below. This differs from the tag_list parameter which is a CSV string:

curl -d "story[title]=A Task With Checklist And Tags" -d "story[workspace_id]=123" -d "story[story_type]=task" -d "story[tag_list]=comma,seperated,value" -d "story[checklist][]=real-query&story[checklist][]=string-encoded-array" "https://api.mavenlink.com/api/v1/stories.json"

Updating an Existing Story

You can edit Stories as follows:

curl -X PUT -d "story[workspace_id]=10" -d "story[title]=Corrected Title" "https://api.mavenlink.com/api/v1/stories/1.json"

The response will contain the JSON representation of the updated Story or an error message indicating which arguments are missing or erroneous.

Any of the required or optional create parameters (except workspace_id and parent_id) can be edited by an update.

The field fixed_fee can only be modified if the story is not related to an active or draft invoice.

Clearing all assignee_ids from a story can be accomplished by sending [] or null.

Destroying an Existing Story

You can delete Stories as follows:

curl -X DELETE "https://api.mavenlink.com/api/v1/stories/1.json"

The response will have no content and HTTP 204 status code if the Story has been successfully deleted, or a JSON error message indicating why the Story could not be deleted.