Stories & Tasks

In the Planbox API an item is called a story. It is analogous to a user story as defined in the Agile or SCRUM. 
The story is the core object in Planbox and contains rich information including these objects: taskscomments and files.


https://work.planbox.com/api/get_story

Retrieves a story object along with all its tasks, past tasks, file attachments and comments.

POST Arguments

  • story_id: Story id.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is an array of stories on success or an error message string upon failure.

A story object has these properties:

  • id: Unique story id
  • priority: Ordered story position.
  • name: Name of story.
  • type: Type of story as listed here.
  • description: Story description.
  • note: Note when the story is blocked or rejected.
  • carried_over_count: Number of times the story has been carried over a next iteration.
  • carried_over_story_ids: Past story ids the story was carried over.
  • carried_over_note: Note as to why the story was carried over last.
  • created_on: Date and time the story was created on.
  • creator_id: Resource id of person who created the story.
  • completed_on: Date and time the story was completed on.
  • due_on: Deadline date when the story is due.
  • status: Satus of the story. Can be one of: pending, inprogress, completed, delivered (verified in UI), accepted, rejected, released or blocked.
  • project_id: Parent project id.
  • product_id: Parent product id. See get_product for more information.
  • iteration_id: Iteration in which the story is contained in.
  • timeframe: Timeframe of the iteration. Can be one of: before_last, last, current, next, after_next or backlog.
  • tags: A comma-sperated list of labels.
  • importance: A number between 0 and 5 which respectively mean: na, nice-to-have, low, normal, high, critical.
  • points: A number of story points as defined in SCRUM methodology.
  • value: A number representing the business value.
  • ticket: Reference to a third-party help desk ticket like Zendesk.
  • baseline: If the baseline feature is turned on, iteration id where the story was orginally planned.
  • blocked: 1 if the story is blocked, or 0 if not.
  • permission: The permission the logged user has on the story. Can be one of: read, write or admin. Inherited from the product permission. See Planbox Permissions for more details.
  • association: The assoication the logged user has on the story. Can be worker or observer. Inherited from the project association.
  • tasks: An array of tasks on this story.
  • past_tasks: An array of past tasks (if the story was carried over multiple iterations) on this story. There will be at least one.
  • files: An array of file attachments on this story. Can be empty.
  • comments: An array of user comments on this story. Can be empty.

A task object has these properties:

  • id: Unique task id.
  • story_id: Parent story id.
  • priority: Ordered task position.
  • name: Name of task.
  • description: Description of task.
  • tags: A comma-sperated list of labels.
  • resource_id: Resource assigned to this task. Will be 0 if unassigned.
  • role_id: Role id assigned to this task.
  • status: Status of the task. Can be one of: pending, in progress or completed.
  • duration: Time logged in hours on this task if status is completed.
  • estimate: Estimate-hours to accomplish this task.
  • timer_start: GMT date and time the timer was started on for this task if status is in progress.
  • timer_sum: Number of seconds accumulated on the timer when task is pending or in progress.

NOTE: When task status is pending, look at timer_sum for logged time ( in seconds). When task status is in progress, logged time is calculated with this formula: now - timer_start + timer_sum (in seconds). When task status is completed, logged time is duration in hours.

A file attachment object has these properties:

  • id: Unique file id.
  • story_id: Parent story id.
  • name: File name of the attachment.
  • mime_type: Mime type of the file.
  • icon: Image URL to preview or icon of the file.
  • date: Date and time when the file was attached.
  • resource_id: Resource who attached this file.
  • size: Size of file in bytes.
  • sizeStr: Human readable string of the size of the file.
  • description:

A comment object has these properties:

  • id: Unique comment id.
  • story_id: Parent story id.
  • to_ids: Array of resource ids that were emailed.
  • resource_id: Resource who wrote the comment.
  • date: Date and time when the comment was created.
  • text: The comment.

Javascript Example

Uses jQuery's post function to fetch story id 1234.

$.post('https://work.planbox.com/api/get_story', {story_id: 1234}, 'json');

https://work.planbox.com/api/get_stories

Retrieves stories for a given product (initiative) and iterations. The list of stories returned is curated based on the permission of the logged user.

POST Arguments

  • product_id[]: Product or products from which to retrieve stories. You can pass a single product id or an array or product ids.
  • timeframe[]: Optional. An array of timeframes or a single timeframe. If omitted (and so is iteration_id), 'current' is used.
  • iteration_id[]: Optional. Array of iteration ids to fetch or a single iteration id. If omitted, timeframe is used instead.
    Note 1: You cannot specify both timeframe and iteration_id.
    Note 2: You cannot speicify this argument is product_id is an array.
  • resource_id[] Optional. Array of resource ids or a single resource id. If specified, only stories with tasks assigned to those resources will be returned.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is an array of stories on success or an error message string upon failure.

Each story object is the same as in API call get_story.

Javascript Example

Uses jQuery's post function to fetch all stories in the Current iteration of product id 1234.

$.post('https://work.planbox.com/api/get_stories', {
product_id: 1234,
timeframe: ['current']
}, 'json');

Similar example but fetches all stories with tasks Not Assigned in the Current iteration of product id 1234.

$.post('https://work.planbox.com/api/get_stories', {
product_id: 1234,
timeframe: ['current'],
resource_id:0
}, 'json');

https://work.planbox.com/api/add_story

Adds a new story in the given product, project and iteration (or timeframe). You can optionally create tasks and attach files.
Note 1: If you omit to create a task, Planbox will automatically create one.
Note 2: You can only link files with URLs. You cannot upload files.

POST Arguments

  • name: Name of story.
  • type: Optional. Type of story.
  • description: Optional. Story description.
  • product_id: Parent product id. See get_products for more information.
  • project_id: Parent project id. See get_projects for more information.
  • iteration_id: Optional. Iteration in which the story is contained in.See get_iterations for more information. Can be omitted iftimeframe is specified.
  • timeframe: Optional. Timeframe of the iteration. Can be one of: current, next, or backlog. Can be omitted if iteration_id is specified.
  • resource_id: Optional. Person to assign the default task to. Omit if you are passing tasks. Must be someone on the project. See attribute resource_ids for get_projects.
  • tags: Optional. A comma-separated list of labels.
  • due_on: Optional. Deadline date when the story is due.
  • importance: Optional. A number between 0 and 5 which respectively mean: na, nice-to-have, low, normal, high, critical. Default is 3 (normal).
  • points: Optional. A number of story points as defined in SCRUM methodology. Default is 0.
  • value: Optional. A number representing the business value. Default is 0.
  • source: Optional. Name of application which created the story. Up to 20 characters allowed. Default is Planbox.
  • tasks: Optional. An array of tasks to create on this story. A task has these attributes:
  •  - name: Name of task.
  •  - description: Description of task.
  •  - tags: A comma-seperated list of labels.
  •  - resource_id: Optional. Resource to assign to this task. Set to 0 or leave blank to keep unassigned.
  •  - role_id: Optional. Role to assign to this task. Default is chosen by Planbox.
  •  - estimate: Optional. Estimate-hours to accomplish this task. Default is 0.
  • files: Optional. An array of file attachments to create on this story. Can be empty.
  •  - name: File name of the attachment.
  •  - url: URL pointing to the file.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> has the two properties described below on success or an error message string upon failure.

On success, <result> has these properties:

  • new_story_id: Unique story id of the newly created story
  • stories: Array of story records. It will contain the new story. See get_story.

Javascript Example

Uses jQuery's post function to create a new bug in the Current iteration or product 1234 and project 5678. Links Planbox' logo as file attachment.

$.post('https://work.planbox.com/api/add_story', {
name: 'Something is broken',
product_id: 1234,
project_id: 5678,
type: 'bug',
timeframe: 'current',
files: [{
name:'logo.png',
url:'https://www.planbox.com/img/logo.png'
}]
}, 'json');

https://work.planbox.com/api/duplicate_story

Duplicates a story and places it after in the same iteration.

POST Arguments

  • story_id: The story to duplicate.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> has stories on success or an error message string upon failure.

On success, stories is an array of stories. It will contain the new story. See get_story.

Javascript Example

Uses jQuery's post function to duplicate story 1234.

$.post('https://work.planbox.com/api/duplicate_story', {story_id: 1234}, 'json');

https://work.planbox.com/api/delete_story

Deletes a story.

Note: This is not reversible. Be careful!

POST Arguments

  • story_id: The story to delete.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is an object on success or an error message string upon failure.

Javascript Example

Uses jQuery's post function to delete story 1234.

$.post('https://work.planbox.com/api/delete_story', {story_id: 1234}, 'json');

https://work.planbox.com/api/update_story

Updates attributes of a story.

POST Arguments

  • story_id: The story to update
  • name: Name of story.
  • type: Optional. Type of story.
  • description: Optional. Story description.
  • tags: Optional. A comma-separated list of labels.
  • due_on: Optional. Deadline date when the story is due.
  • importance: Optional. A number between 0 and 5 which respectively mean: na, nice-to-have, low, normal, high, critical. Default is 3 (normal).
  • points: Optional. A number of story points as defined in SCRUM methodology. Default is 0.
  • value: Optional. A number representing the business value. Default is 0.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> has stories on success or an error message string upon failure.

On success, stories is an array of stories. It will contain the updated story. See get_story.

Javascript Example

Uses jQuery's post function to update the attributes name and tags for story 1234.

$.post('https://work.planbox.com/api/update_story', {
story_id: 1234,
name: 'Request from customers',
tags: 'ACME, Intel'
}, 'json');

https://work.planbox.com/api/move_story

Moves a story before or after another neighbor story. Changes the story's priority. Use this to change the order stories are listed in iteration.

Note: The neighbor story must be in the same iteration.

POST Arguments

  • story_id: The story to move.
  • neighbor_id: The neighbor story.
  • position: The relative position to the neighbor. Can be before or after.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> has an array of updated stories on success or an error message string upon failure.

Planbox returns the full story object. See get_story for details. In addition, it returns partial objects for all other stories in the iteration to update their priority. The partials will contain attributes id and priority.

Javascript Example

Uses jQuery's post function to moves story 1234 after story 5678.

$.post('https://work.planbox.com/api/move_story', {
story_id: 1234,
neighbor_id: 5678,
position: 'after'
}, 'json');

https://work.planbox.com/api/move_story_to_iteration

Moves a story to another iteration. You can specify the timeframe or the actual iteration.

Note: The target iteration must be in the same product.

POST Arguments

  • story_id: The story to move.
  • iteration_id: Optional. The target iteration.
  • timeframe: Optional. The target iteration timeframe.
  • position: The target position in the iteration. Can be top or bottom.

Note: Arguments iteration_id and timeframe are mutually exclusive.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> has an array of updated stories on success or an error message string upon failure.

Planbox returns the full story object. See get_story for details. In addition, it returns partial objects for all other stories in the iteration to update their priority. The partials will contain attributes id and priority.

Javascript Example

Uses jQuery's post function to moves story 1234 in the top of the Backlog.

$.post('https://work.planbox.com/api/move_story_to_iteration', {
story_id: 1234,
timeframe: 'backlog',
position: 'top'
}, 'json');

https://work.planbox.com/api/move_story_to_project

Moves a story to another project.

Note: The target project must be part of the story's present product.

POST Arguments

  • story_id: The story to move.
  • project_id: The target project.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> has an array of updated stories on success or an error message string upon failure.

Planbox returns the full story object. See get_story for details.

Javascript Example

Uses jQuery's post function to moves story 1234 in project 1212.

$.post('https://work.planbox.com/api/move_story_to_project', {
story_id: 1234,
project_id: 1212
}, 'json');

https://work.planbox.com/api/move_story_to_product

Moves a story to another product and project. You can specify the timeframe or the actual iteration.

Note: The target product must be different than the story's present product.

POST Arguments

  • story_id: The story to move.
  • product_id: The target product.
  • project_id: The target project.
  • iteration_id: Optional. The target iteration.
  • timeframe: Optional. The target iteration timeframe.
  • position: The target position in the iteration. Can be top or bottom.

Note: Arguments iteration_id and timeframe are mutually exclusive.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> has an array of updated stories on success or an error message string upon failure.

Planbox returns the full story object. See get_story for details.

Javascript Example

Uses jQuery's post function to moves story 1234 in the top of the Backlog in product 4567 and project 1212.

$.post('https://work.planbox.com/api/move_story_to_product', {
story_id: 1234,
product_id: 5678,
project_id: 1212,
timeframe: 'backlog',
position: 'top'
}, 'json');

https://work.planbox.com/api/add_task

Adds a new task to a story.

If you omit resource_id and/or role_id, Planbox will try to determine the best person/role to be assigned the task. You can force the task to be unassigned by setting resource_id to 0.

Note: Attributes timer_sumtimer_startduration and status are described in update_task.

POST Arguments

  • story_id: The parent story.
  • name: Optional. Name of the task.
  • description: Optional. Description of task.
  • tags: Optional. A comma-separated list of labels.
  • resource_id: Optional. Resource assigned to this task. If omitted, Planbox will choose someone. Set to 0 to keep unassigned.
  • role_id: Optional. Role id assigned to this task. If omitted, Planbox will choose a role.
  • estimate: Optional. Estimate-hours to accomplish this task. Default is 0.
  • duration: Optional. Logged hours to accomplish this task. Default is 0.
  • timer_start: Optional. Date/time when the last timer started for the task if in progress. Must be in the form YYYY-MM-DD HH:MM:SS and in the GMT timezone. Default is null.
  • timer_sum: Optional. Number of seconds accumulated for the task if pending or in progress. Default it 0.
  • status: Optional. The new status of the task. Can be one of: pendinginprogress or completed. Default is pending.
    Note: If you set status to inprogress and do not specify timer_start, Planbox will start the timer now.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an object on success or an error message string upon failure. The object contains arrays of modified stories and tasks.

Javascript Example

Uses jQuery's post function to add a new unassigned task to story 1234.

$.post('https://work.planbox.com/api/add_task', {
story_id: 1234,
resource_id: 0
}, 'json');

https://work.planbox.com/api/update_task

Updates an existing task. Omit attributes not to change them.

About task logged time and status

Three attributes are used to store and accumulate logged time: timer_sumtimer_start and duration. Logged time is calculated using these attributes depending on the task status.

  • When a task is pending, logged time is specified by timer_sum in seconds.
  • When a task is inprogress, logged time is timer_sum plus current date/time minus timer_start.
    Note that date/time are in GMT timezone.
  • When a task is completed, logged time is duration in hours.

You complete a story by setting status to completed. Planbox will use timer_sum and timer_start to calculate and set duration in hours. Alternatively you can set duration explicitly during that call.

POST Arguments

  • task_id: The task to modify.
  • story_id: The parent story.
  • name: Optional. Name of the task.
  • description: Optional. Description of task.
  • tags: Optional. A comma-separated list of labels.
  • resource_id: Optional. Resource assigned to this task.
  • role_id: Optional. Role id assigned to this task.
  • estimate: Optional. Estimate-hours to accomplish this task.
  • duration: Optional. Logged hours to accomplish this task.
  • timer_start: Optional. Date/time when the last timer started for the task if in progress. Must be in the form YYYY-MM-DD HH:MM:SS and in the GMT timezone.
  • timer_sum: Optional. Number of seconds accumulated for the task if pending or in progress.
  • status: Optional. The new status of the task. Can be one of: pendinginprogress or completed.
    Note: If you set status to inprogress and do not specify timer_start, Planbox will start the timer now.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an object on success or an error message string upon failure. The object contains arrays of modified stories and tasks.

Javascript Example

Uses jQuery's post function to completed task 5678 in story 1234. Sets logged time to 3 hours.

$.post('https://work.planbox.com/api/update_task', {
story_id: 1234,
task_id: 5678
duration: 3,
status: 'completed'
}, 'json');

https://work.planbox.com/api/delete_task

Deletes a task.

Note: This is not reversible. Be careful!

POST Arguments

  • story_id: The parent story.
  • task_id: The task to delete.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an object on success or an error message string upon failure.

Javascript Example

Uses jQuery's post function to delete task 5678 in story 1234.

$.post('https://work.planbox.com/api/delete_task', {
story_id: 1234,
task_id: 5678
}, 'json');


https://work.planbox.com/api/comment_story

Adds a new comment to a story.

POST Arguments

  • story_id: The story id.
  • text: The comment you want to add to the story.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Javascript Example

Uses jQuery's post function to add a comment to story 1234.

$.post('https://work.planbox.com/api/add_story', {
story_id: 1234,
text: "A test comment"
}, 'json');


NOTE: We are always looking to improve our API. Email us any suggestions at help@planbox.com to help us prioritize.

Feedback and Knowledge Base