V1 Web API

API

MY_ACCESS_TOKEN is to be replaced by a token for a given user obtained from https://my.example.org/#!/profile/tokens initially. The User Tokens section of the api documentation gives instructions for obtaining subsequent tokens.

Projects

GET /v1/projects

Retrieve a list of projects.

Example:

curl https://my.example.org/api/v1/projects
Parameters:
  • marker (int) – The resource id where the page should begin.
  • offset (int) – The offset to start the page at.
  • limit (int) – The number of projects to retrieve.
  • name (str) – A string to filter the name by.
  • description (str) – A string to filter the description by.
  • project_group_id (int) – The ID of a project group to which the projects must belong.
  • subscriber_id (int) – The ID of a subscriber to filter results by.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Project)

POST /v1/projects

Create a new project.

Note

This command is only available to Admin users.

Example:

curl https://my.example.org/api/v1/projects \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"name":"test-project",\
                "description":"A test project"}'
Parameters:
  • project (Project) – A project within the request body.
Return type:

Project

PUT /v1/projects

Modify this project.

Note

This command is only available to Admin users.

Example:

curl https://my.example.org/api/v1/projects/10 -X PUT \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"name":"test-project-update",\
                "description":"An updated test project"}'
Parameters:
  • project_id (int) – An ID of the project.
  • project (Project) – A project within the request body.
Return type:

Project

The search endpoint for projects.

Example:

curl https://my.example.org/api/v1/projects/search?q=cloud
Parameters:
  • q (str) – The query string.
Return:

List of Projects matching the query.

Return type:

list(Project)

Project Groups

GET /v1/project_groups

Retrieve a list of projects groups.

Example:

curl https://my.example.org/api/v1/project_groups
Parameters:
  • marker (int) – The resource id where the page should begin.
  • offset (int) – The offset to start the page at.
  • limit (int) – The number of project groups to retrieve.
  • name (str) – A string to filter the name by.
  • title (str) – A string to filter the title by.
  • subscriber_id (int) – The ID of a subscriber to filter by.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(ProjectGroup)

POST /v1/project_groups
Create a new project group.
This command is only available to Admin users.

Example:

curl https://my.example.org/api/v1/project_groups \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"title":"test-group","name":"test-group"}'
Parameters:
  • project_group (ProjectGroup) – A project group within the request body.
Return type:

ProjectGroup

PUT /v1/project_groups
Modify this project group.
This command is only available to Admin users.

Example:

curl https://my.example.org/api/v1/project_groups/17 -X PUT \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"id":17,"name":"test-group",\
                "title":"test-group-that-is-changed"}'
Parameters:
  • project_group_id (int) – An ID of the project group.
  • project_group (ProjectGroup) – A project group within the request body.
Return type:

ProjectGroup

DELETE /v1/project_groups
Delete this project group.
This command is only available to Admin users.

Example:

curl https://my.example.org/api/v1/project_groups/17 -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • project_group_id (int) – An ID of the project group.
GET /v1/project_groups/<project_group_id>/projects

Get projects inside a project group.

Example:

curl https://my.example.org/api/v1/project_groups/55/projects
Parameters:
  • project_group_id (str) – An ID or name of the project group.
Return type:

list(Project)

PUT /v1/project_groups/<project_group_id>/projects
Add a project to a project_group.
This command is only available to Admin users.

Example:

curl https://my.example.org/api/v1/project_groups/17/projects/17 \
-X PUT -H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{}'
Parameters:
  • project_group_id (int) – An ID of the project group.
  • project_id (int) – An ID of project in this project group.
Return type:

Project

DELETE /v1/project_groups/<project_group_id>/projects
Delete a project from a project_group.
This command is only available to Admin users.

Example:

curl https://my.example.org/api/v1/project_groups/17/projects/1 \
-X DELETE -H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • project_group_id (int) – An ID of the project group.
  • project_id (int) – An ID of project in this project group.

Stories

GET /v1/stories

Retrieve definitions of all of the stories.

Example:

curl https://my.example.org/api/v1/stories
Parameters:
  • title (str) – A string to filter the title by.
  • description (str) – A string to filter the description by.
  • status (list(str)) – Only show stories with this particular status.
  • assignee_id (int) – Filter stories by who they are assigned to.
  • creator_id (int) – Filter stories by who created them.
  • project_group_id (int) – Filter stories by project group.
  • project_id (int) – Filter stories by project ID.
  • subscriber_id (int) – Filter stories by subscriber ID.
  • tags (list(str)) – A list of tags to filter by.
  • updated_since (datetime) – Filter stories by last updated time.
  • marker (int) – The resource id where the page should begin.
  • offset (int) – The offset to start the page at.
  • limit (int) – The number of stories to retrieve.
  • tags_filter_type (str) – Type of tags filter.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Story)

GET /v1/stories/(story_id)

Retrieve details about one story.

Example:

curl https://my.example.org/api/v1/stories/11
Parameters:
  • story_id (int) – An ID of the story.
Return type:

Story

POST /v1/stories

Create a new story.

Example:

curl 'https://my.example.org/api/v1/stories' \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"title":"Test Story","description":"A test story."}'
Parameters:
  • story (Story) – A story within the request body.
Return type:

Story

PUT /v1/stories

Modify this story.

Example:

curl 'https://my.example.org/api/v1/stories/19' -X PUT \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"title":"Modified","description":"New description."}'
Parameters:
  • story_id (int) – An ID of the story.
  • story (Story) – A story within the request body.
Return type:

Story

DELETE /v1/stories

Delete this story. This command is only available to Admin users.

Example:

curl 'https://my.example.org/api/v1/stories/5' -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • story_id (int) – An ID of the story.

The search endpoint for stories.

Example:

curl https://my.example.org/api/v1/stories/search?q=pep8
Parameters:
  • q (str) – The query string.
  • status (list(str)) – Only show stories with this particular status.
  • assignee_id (int) – Filter stories by who they are assigned to.
  • creator_id (int) – Filter stories by who created them.
  • project_group_id (int) – Filter stories by project group.
  • project_id (int) – Filter stories by project ID.
  • subscriber_id (int) – Filter stories by subscriber ID.
  • tags (list(str)) – A list of tags to filter by.
  • updated_since (datetime) – Filter stories by last updated time.
  • marker (int) – The resource id where the page should begin.
  • offset (int) – The offset to start the page at.
  • limit (int) – The number of stories to retrieve.
  • tags_filter_type (str) – Type of tags filter.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return:

List of Stories matching the query and any other filters.

Return type:

list(Story)

GET /v1/stories/<story_id>/tasks

Retrieve definitions of all of the tasks associated with a story.

Example:

curl https://my.example.org/api/v1/stories/11/tasks
Parameters:
  • story_id (int) – filter tasks by story ID.
  • title (str) – search by task title.
  • assignee_id (int) – filter tasks by who they are assigned to.
  • project_id (int) – filter the tasks based on project.
  • project_group_id (int) – filter tasks based on project group.
  • branch_id (int) – filter tasks based on branch_id.
  • milestone_id (int) – filter tasks based on milestone.
  • status (list(str)) – filter tasks by status.
  • priority (list(str)) – filter tasks by priority.
  • marker (int) – The resource id where the page should begin.
  • limit (int) – The number of tasks to retrieve.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – sort direction for results (asc, desc).
Return type:

list(Task)

GET /v1/stories/<story_id>/tasks/(story_id)

Retrieve details about one task.

Example:

curl https://my.example.org/api/v1/stories/11/tasks/2691
Parameters:
  • story_id (int) – An ID of the story.
  • task_id (int) – An ID of the task.
Return type:

Task

POST /v1/stories/<story_id>/tasks

Create a new task.

Example:

curl 'https://my.example.org/api/v1/stories/19/tasks' \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"title":"Task Foo","project_id":153,"key":"todo"}'
Parameters:
  • story_id (int) – An ID of the story.
  • task (Task) – a task within the request body.
Return type:

Task

PUT /v1/stories/<story_id>/tasks

Modify this task.

Example:

curl 'https://my.example.org/api/v1/stories/19/tasks/19' -X PUT \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"title":"Task Foio","project_id":153,"key":"todo"}'
Parameters:
  • story_id (int) – An ID of the story.
  • task_id (int) – An ID of the task.
  • task (Task) – a task within the request body.
Return type:

Task

DELETE /v1/stories/<story_id>/tasks

Delete this task.

Example:

curl 'https://my.example.org/api/v1/stories/11/tasks/28' -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • story_id (int) – An ID of the story.
  • task_id (int) – An ID of the task.

Comments and Timeline events

GET /v1/stories/<story_id>/comments

Retrieve all comments posted under specified story.

Example:

curl https://my.example.org/api/v1/stories/11/comments
Parameters:
  • story_id (int) – Filter comments by story ID.
  • marker (int) – The resource id where the page should begin.
  • limit (int) – The number of comments to retrieve.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Comment)

GET /v1/stories/<story_id>/comments/(story_id)

Retrieve details about one comment.

Example:

curl https://my.example.org/api/v1/stories/11/comments/6834
Parameters:
  • story_id (int) – An ID of the story. It stays in params as a placeholder so that pecan knows where to match an incoming value. It will stay unused, as far as comments have their own unique ids.
  • comment_id (int) – An ID of the comment.
Return type:

Comment

POST /v1/stories/<story_id>/comments

Create a new comment.

Example:

curl https://my.example.org/api/v1/stories/19/comments \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"content":"creating a new comment"}'
Parameters:
  • story_id (int) – An id of a Story to add a Comment to.
  • comment (Comment) – The comment itself.
Return type:

TimeLineEvent

PUT /v1/stories/<story_id>/comments

Update an existing comment. This command is disabled by default.

Parameters:
  • story_id (int) – A placeholder.
  • comment_id (int) – The id of a Comment to be updated.
  • comment_body (Comment) – An updated Comment.
Return type:

Comment

DELETE /v1/stories/<story_id>/comments

Delete an existing comment. This command is disabled by default.

Parameters:
  • story_id (int) – A placeholder.
  • comment_id (int) – The id of a Comment to be updated.
GET /v1/events

Retrieve a filtered list of all events.

With no filters or limit set this will likely take a long time and return a very long list. Applying some filters is recommended.

Example:

curl https://my.example.org/api/v1/events
Parameters:
  • story_id (int) – Filter events by story ID.
  • worklist_id (int) – Filter events by worklist ID.
  • board_id (int) – Filter events by board ID.
  • event_type (list(str)) – A selection of event types to get.
  • offset (int) – The offset to start the page at.
  • limit (int) – The number of events to retrieve.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(TimeLineEvent)

GET /v1/events/(event_id)

Retrieve details about one event.

Example:

curl https://my.example.org/api/v1/events/15994
Parameters:
  • event_id (int) – An ID of the event.
Return type:

TimeLineEvent

GET /v1/stories/<story_id>/events

Retrieve all events that have happened under specified story.

Example:

curl https://my.example.org/api/v1/stories/11/events
Parameters:
  • story_id (int) – Filter events by story ID.
  • event_type (list(str)) – A selection of event types to get.
  • marker (int) – The resource id where the page should begin.
  • offset (int) – The offset to start the page at.
  • limit (int) – The number of events to retrieve.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(TimeLineEvent)

GET /v1/stories/<story_id>/events/(story_id)

Retrieve details about one event.

Example:

curl https://my.example.org/api/v1/stories/11/events/15994
Parameters:
  • story_id (int) – An ID of the story. It stays in params as a placeholder so that pecan knows where to match an incoming value. It will stay unused, as far as events have their own unique ids.
  • event_id (int) – An ID of the event.
Return type:

TimeLineEvent

Tasks

GET /v1/tasks

Retrieve definitions of all of the tasks.

Example:

curl https://my.example.org/api/v1/tasks
Parameters:
  • title (str) – Search by task title.
  • story_id (int) – Filter tasks by story ID.
  • assignee_id (int) – Filter tasks by who they are assigned to.
  • project_id (int) – Filter the tasks based on project.
  • project_group_id (int) – Filter tasks based on project group.
  • branch_id (int) – Filter tasks based on branch_id.
  • milestone_id (int) – Filter tasks based on milestone.
  • status (list(str)) – Filter tasks by status.
  • priority (list(str)) – Filter tasks by priority.
  • marker (int) – The resource id where the page should begin.
  • limit (int) – The number of tasks to retrieve.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Task)

GET /v1/tasks/(task_id)

Retrieve details about one task.

Example:

curl https://my.example.org/api/v1/tasks/24
Parameters:
  • task_id (int) – An ID of the task.
Return type:

Task

POST /v1/tasks

Create a new task.

Example:

curl https://my.example.org/api/v1/tasks \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"story_id":19,"title":"Task Foo",\
                "project_id":153,"status":"todo"}'
Parameters:
  • task (Task) – a task within the request body.
Return type:

Task

PUT /v1/tasks

Modify this task.

Example:

curl https://my.example.org/api/v1/tasks -X PUT \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"task_id":27,"status":"merged"}'
Parameters:
  • task_id (int) – An ID of the task.
  • task (Task) – A task within the request body.
Return type:

Task

DELETE /v1/tasks

Delete this task.

Example:

curl https://my.example.org/api/v1/tasks/27 -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • task_id (int) – An ID of the task.

Search and filter the tasks.

Example:

curl https://my.example.org/api/v1/tasks/search?q=mary
Parameters:
  • q (str) – Fulltext search query parameter.
  • story_id (int) – Filter tasks by story ID.
  • assignee_id (int) – Filter tasks by who they are assigned to.
  • project_id (int) – Filter the tasks based on project.
  • project_group_id (int) – Filter tasks based on project group.
  • branch_id (int) – Filter tasks based on branch_id.
  • milestone_id (int) – Filter tasks based on milestone.
  • status (list(str)) – Filter tasks by status.
  • offset (int) – The offset to start the results at.
  • limit (int) – The number of tasks to retrieve.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return:

List of Tasks matching the query.

Return type:

list(Task)

Branches

GET /v1/branches

Retrieve a list of branches.

Example:

curl https://my.example.org/api/v1/branches
Parameters:
  • marker (int) – The resource id where the page should begin.
  • limit (int) – The number of branches to retrieve.
  • name (str) – Filter branches based on name.
  • project_id (int) – Filter branches based on project.
  • project_group_id (int) – Filter branches based on project group.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Branch)

GET /v1/branches/(branch_id)

Retrieve information about the given branch.

Example:

curl https://my.example.org/api/v1/branches/42
Parameters:
  • branch_id (int) – Branch ID.
Return type:

Branch

POST /v1/branches

Create a new branch.

Example:

TODO
Parameters:
  • branch (Branch) – A branch within the request body.
Return type:

Branch

PUT /v1/branches

Modify this branch.

Example:

TODO
Parameters:
  • branch_id (int) – An ID of the branch.
  • branch (Branch) – A branch within the request body.
Return type:

Branch

Milestones

GET /v1/milestones

Retrieve a list of milestones.

Parameters:
  • marker (int) – The resource id where the page should begin.
  • limit (int) – The number of milestones to retrieve.
  • name (str) – Filter milestones based on name.
  • branch_id (int) – Filter milestones based on branch_id.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Milestone)

GET /v1/milestones/(milestone_id)

Retrieve information about the given milestone.

Parameters:
  • milestone_id (int) – Milestone ID.
Return type:

Milestone

POST /v1/milestones

Create a new milestone.

Parameters:
  • milestone (Milestone) – A milestone within the request body.
Return type:

Milestone

PUT /v1/milestones

Modify this milestone.

Parameters:
  • milestone_id (int) – An ID of the milestone.
  • milestone (Milestone) – A milestone within the request body.
Return type:

Milestone

Tags

GET /v1/tags

Retrieve all tags.

Example:

curl https://my.example.org/api/v1/tags
Parameters:
  • story_id (int) – Filter tags by story ID.
  • name (str) – Filter tags by name.
  • marker (int) – ID of the tag to start results from.
  • limit (int) – Maximum number of results per page.
  • offset (int) – Number of results to offset page by.
Return type:

list(Tag)

GET /v1/tags/(tag_id)

Retrieve details about one tag.

Example:

curl https://my.example.org/api/v1/tags/159
Parameters:
  • tag_id (int) – An ID of the tag.
Return type:

Tag

POST /v1/tags

Create a tag not attached to any Story.

Example:

curl https://my.example.org/api/v1/tags \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"tag_name":"created-via-api"}'
Parameters:
  • tag_name (str) – The name of a new tag.
Return type:

Tag

PUT /v1/tags

Add a list of tags to a Story.

Example:

curl https://my.example.org/api/v1/tags/19 -X PUT \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '["taga","tagb"]'
Parameters:
  • story_id (int) – An id of a Story to which the tags should be added.
  • tags (list(str)) – A list of tags to be added.
Return type:

Story

DELETE /v1/tags

Remove a list of tags from a Story.

Example:

curl https://my.example.org/api/v1/tags/19 -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '["taga","tagb"]'
Parameters:
  • story_id (int) – An id of a Story from which the tags should be removed.
  • tags (list(str)) – A list of tags to be removed.

Subscriptions

GET /v1/subscriptions

Retrieve a list of subscriptions for the authorized user.

Example:

curl https://my.example.org/api/v1/subscriptions \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • marker (int) – The resource id where the page should begin.
  • limit (int) – The number of subscriptions to retrieve.
  • target_type (list(str)) – The type of resource to search by.
  • target_id (int) – The unique ID of the resource to search by.
  • user_id (int) – The unique ID of the user to search by.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Subscription)

GET /v1/subscriptions/(subscription_id)

Retrieve a specific subscription record.

Example:

curl https://my.example.org/api/v1/subscriptions/4 \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • subscription_id (int) – The unique id of this subscription.
Return type:

Subscription

POST /v1/subscriptions
Create a new subscription.
Note: target_id is the same value as the story_id of a story.

Example:

curl https://my.example.org/api/v1/subscriptions \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"target_type":"story","target_id":8}'
Parameters:
  • subscription (Subscription) – A subscription within the request body.
Return type:

Subscription

DELETE /v1/subscriptions

Delete a specific subscription.

Example:

curl https://my.example.org/api/v1/subscriptions/10 -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • subscription_id (int) – The unique id of the subscription to delete.

Users

GET /v1/users

Page and filter the users in storyboard.

Example:

curl https://my.example.org/api/v1/users
Parameters:
  • marker (int) – The resource id where the page should begin.
  • offset (int) – The offset to start the page at.
  • limit (int) – The number of users to retrieve.
  • full_name (str) – A string of characters to filter the full_name with.
  • email (str) – A string of characters to filter the email with.
  • openid (str) – A string of characters to filter the openid with.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(User)

GET /v1/users/(user_id)

Retrieve details about one user.

Example:

curl https://my.example.org/api/v1/users/21
Parameters:
  • user_id (int) – The unique id of this user
Return type:

User

POST /v1/users
Create a new user.
This command is only available to Admin users.

Example:

TODO
Parameters:
  • user (User) – A user within the request body.
Return type:

User

PUT /v1/users

Modify this user. Admin users can edit the user details of any user, authenticated users can only modify their own details.

Example:

curl https://my.example.org/api/v1/users/21 -X PUT \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"email":"user@my.example.org"}'
Parameters:
  • user_id (int) – Unique id to identify the user.
  • user (User) – A user within the request body.
Return type:

User

The search endpoint for users.

Example:

curl https://my.example.org/api/v1/users/search?q=James
Parameters:
  • q (str) – The query string.
Return:

List of Users matching the query.

Return type:

list(User)

GET /v1/users/self

Return the currently logged in user

Example:

curl https://my.example.org/api/v1/users/self \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Return:The User record for the current user.
Return type:User

Teams

GET /v1/teams

Retrieve a list of teams.

Example:

curl https://my.example.org/api/v1/teams
Parameters:
  • offset (int) – The offset at which to start the page.
  • marker (int) – The resource id where the page should begin.
  • limit (int) – The number of teams to retrieve.
  • name (str) – A string to filter the name by.
  • description (str) – A string to filter the description by.
  • project_id (int) – The ID of a project to filter by.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Team)

POST /v1/teams

Create a new team.

Example:

TODO
Parameters:
  • team (Team) – a team within the request body.
Return type:

Team

PUT /v1/teams

Modify this team.

Example:

TODO
Parameters:
  • team_id (int) – An ID of the team.
  • team (Team) – A team within the request body.
Return type:

Team

DELETE /v1/teams

Delete this team.

Example:

TODO
Parameters:
  • team_id (int) – An ID of the team.
GET /v1/teams/<team_id>/users

Get users inside a team.

Example:

curl https://my.example.org/api/v1/teams/1/users
Parameters:
  • team_id (int) – An ID of the team.
Return type:

list(User)

PUT /v1/teams/<team_id>/users

Add a user to a team.

Example:

TODO
Parameters:
  • team_id (int) – An ID of the team.
  • user_id (int) – An ID of the user.
Return type:

User

DELETE /v1/teams/<team_id>/users

Delete a user from a team.

Example:

TODO
Parameters:
  • team_id (int) – An ID of the team.
  • user_id (int) – An ID of the user.

User Preferences

GET /v1/users/<user_id>/preferences

Return all preferences for the current user.

Example:

curl https://my.example.org/api/v1/users/21/preferences \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • user_id (int) – An ID of the user.
Return type:

dict(str: str)

POST /v1/users/<user_id>/preferences

Allow a user to update their preferences. Note that a user must explicitly set a preference value to Null/None to have it deleted.

Example:

curl https://my.example.org/api/v1/users/21/preferences \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"display_events_tags_added":"false"}'
Parameters:
  • user_id (int) – The ID of the user whose preferences we’re updating.
  • body (dict(str: str)) – A dictionary of preference values.
Return type:

dict(str: str)

System Info

GET /v1/systeminfo

Retrieve the Storyboard system information.

Example:

curl https://my.example.org/api/v1/systeminfo
Return type:SystemInfo

User Tokens

GET /v1/users/<user_id>/tokens

Returns all the access tokens with matching refresh tokens for the provided user.

Example:

curl https://my.example.org/api/v1/users/21/tokens \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • user_id (int) – The ID of the user.
  • marker (int) – The marker record at which to start the page.
  • limit (int) – The number of records to return.
  • sort_field (str) – The field on which to sort.
  • sort_dir (str) – The direction to sort.
Return:

A list of access tokens for the given user.

Return type:

list(AccessToken)

GET /v1/users/<user_id>/tokens

Returns a specific access token with assigned refresh token for the given user. Admin users can specify any user id, regular users can only use their own.

Example:

curl https://my.example.org/api/v1/users/2/tokens \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • user_id (int) – The ID of the user.
  • access_token_id (int) – The ID of the access token.
Return:

The requested access token.

Return type:

AccessToken

POST /v1/users/<user_id>/tokens

Create a new access token with assigned refresh token for the given user. Admin users can specify any user id, regular users can only use their own.

Example:

curl https://my.example.org/api/v1/users/2/tokens \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"expires_in": 3600, "user_id": 2}'
Parameters:
  • user_id (int) – The user ID of the user.
  • body (AccessToken) – The access token.
Return:

The created access token.

Return type:

AccessToken

PUT /v1/users/<user_id>/tokens

Update an access token for the given user. Admin users can edit any token, regular users can only edit their own.

Example:

curl https://my.example.org/api/v1/users/2/tokens/1764 \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"expires_in": 7200, "user_id": 2}'
Parameters:
  • user_id (int) – The user ID of the user.
  • access_token_id (int) – The ID of the access token.
  • body (AccessToken) – The access token.
Return:

The created access token.

Return type:

AccessToken

DELETE /v1/users/<user_id>/tokens

Deletes an access token with assigned refresh token for the given user. Admin users can delete any access tokens, regular users can only delete their own.

Example:

curl https://my.example.org/api/v1/users/2/tokens/1764 -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • user_id (int) – The user ID of the user.
  • access_token_id (int) – The ID of the access token.
Return:

Empty body, or error response.

DELETE /v1/users/<user_id>/tokens/delete_all

Deletes all access tokens for the given user.

Example:

curl https://my.example.com/v1/users/2/tokens/delete_all -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • user_id (int) – The user ID of the user.
Return type:

AccessToken

Worklists

GET /v1/worklists

Retrieve definitions of all of the worklists.

Example:

curl https://my.example.org/api/v1/worklists
Parameters:
  • title (str) – A string to filter the title by.
  • creator_id (int) – Filter worklists by their creator.
  • project_id (int) – Filter worklists by project ID.
  • archived (bool) – Filter worklists by whether they are archived or not.
  • user_id (int) – Filter worklists by the users with permissions.
  • story_id (int) – Filter worklists by whether they contain a story.
  • task_id (int) – Filter worklists by whether they contain a task.
  • hide_lanes (bool) – If true, don’t return worklists which are lanes in a board.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
  • item_type (str) – Used when filtering by story_id. If item_type is ‘story’ then only return worklists that contain the story, if item_type is ‘task’ then only return worklists that contain tasks from the story, otherwise return worklists that contain the story or tasks from the story.
  • board_id (int) – Get all worklists in the board with this id. Other filters are not applied.
  • subscriber_id (int) – Filter worklists by whether a user is subscribed.
  • offset (int) – Offset at which to begin the results.
  • limit (int) – Maximum number of results to return.
Return type:

list(Worklist)

GET /v1/worklists/(worklist_id)

Retrieve details about one worklist.

Example:

curl https://my.example.org/api/v1/worklists/27
Parameters:
  • worklist_id (int) – The ID of the worklist.
Return type:

Worklist

POST /v1/worklists

Create a new worklist.

Example:

curl https://my.example.org/api/v1/worklists \
-H 'Authorization: Bearer MY_ACCESS_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary '{"title":"create worklist via api"}'
Parameters:
  • worklist (Worklist) – A worklist within the request body.
Return type:

Worklist

PUT /v1/worklists

Modify this worklist.

Example:

TODO
Parameters:
  • id (int) – The ID of the worklist.
  • worklist (Worklist) – A worklist within the request body.
Return type:

Worklist

DELETE /v1/worklists
Archive this worklist.
Though this uses the DELETE command, the worklist is not deleted. Archived worklists remain viewable at the designated URL, but are not returned in search results nor appear on your dashboard.

Example:

curl https://my.example.org/api/v1/worklists/30 -X DELETE \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • worklist_id (int) – The ID of the worklist to be archived.

Filters

GET /v1/worklists/<worklist_id>/filters

Get filters for an automatic worklist.

Example:

curl https://my.example.org/api/v1/worklists/49/filters
Parameters:
  • worklist_id (int) – The ID of the worklist.
Return type:

list(WorklistFilter)

GET /v1/worklists/<worklist_id>/filters/(worklist_id)

Get a single filter for the worklist.

Example:

curl https://my.example.org/api/v1/worklists/49/filters/20
Parameters:
  • worklist_id (int) – The ID of the worklist.
  • filter_id (int) – The ID of the filter.
Return type:

WorklistFilter

POST /v1/worklists/<worklist_id>/filters

Create a new filter for the worklist.

Example:

TODO
Parameters:
  • worklist_id (int) – The ID of the worklist to set the filter on.
  • filter (WorklistFilter) – The filter to set.
Return type:

WorklistFilter

PUT /v1/worklists/<worklist_id>/filters

Update a filter on the worklist.

Example:

TODO
Parameters:
  • worklist_id (int) – The ID of the worklist.
  • filter_id (int) – The ID of the filter to be updated.
  • filter (WorklistFilter) – The new contents of the filter.
Return type:

WorklistFilter

DELETE /v1/worklists/<worklist_id>/filters

Delete a filter from a worklist.

Example:

TODO
Parameters:
  • worklist_id (int) – The ID of the worklist.
  • filter_id (int) – The ID of the filter to be deleted.

Items

GET /v1/worklists/<worklist_id>/items

Get items inside a worklist.

Example:

curl https://my.example.org/api/v1/worklists/49/items
Parameters:
  • worklist_id (int) – The ID of the worklist.
Return type:

list(WorklistItem)

POST /v1/worklists/<worklist_id>/items

Add an item to a worklist.

Example:

TODO
Parameters:
  • id (int) – The ID of the worklist.
  • item_id (int) – The ID of the item.
  • item_type (str) – The type of the item (i.e. “story” or “task”).
  • list_position (int) – The position in the list to add the item.
Return type:

WorklistItem

PUT /v1/worklists/<worklist_id>/items

Update a WorklistItem.

Example:

TODO

This method also updates the positions of other items in affected worklists, if necessary.

Parameters:
  • id (int) – The ID of the worklist.
  • item_id (int) – The ID of the worklist_item to be moved.
  • display_due_date (int) – The ID of the due date displayed on the item.
Return type:

WorklistItem

DELETE /v1/worklists/<worklist_id>/items

Remove an item from a worklist.

Example:

TODO
Parameters:
  • id (int) – The ID of the worklist.
  • item_id (int) – The ID of the worklist item to be removed.

Permissions

GET /v1/worklists/<worklist_id>/permissions

Get worklist permissions for the current user.

Example:

curl https://my.example.org/api/v1/worklists/31/permissions \
-H 'Authorization: Bearer MY_ACCESS_TOKEN'
Parameters:
  • worklist_id (int) – The ID of the worklist.
Return type:

list(str)

POST /v1/worklists/<worklist_id>/permissions

Add a new permission to the worklist.

Example:

TODO
Parameters:
  • worklist_id (int) – The ID of the worklist.
  • permission (dict(str: str)) – The dict to use to create the permission.
Return type:

str

PUT /v1/worklists/<worklist_id>/permissions

Update a permission of the worklist.

Example:

TODO

This takes a dict in the form:

{
    "codename": "my-permission",
    "users": [
        1,
        2,
        3
    ],
    "teams": [
        1,
        6
    ]
}

The given codename must match an existing permission’s codename.

Parameters:
  • worklist_id (int) – The ID of the worklist.
  • permission (dict(str: str)) – The new contents of the permission.
Return type:

str

Boards

GET /v1/boards

Retrieve definitions of all of the boards.

Parameters:
  • title (str) – A string to filter the title by.
  • creator_id (int) – Filter boards by their creator.
  • project_id (int) – Filter boards by project ID.
  • archived (bool) – Filter boards by whether they are archived or not.
  • story_id (int) – Filter boards by whether they contain a story.
  • task_id (int) – Filter boards by whether they contain a task.
  • item_type (str) – Used when filtering by story_id. If item_type is ‘story’ then only return worklists that contain the story, if item_type is ‘task’ then only return worklists that contain tasks from the story, otherwise return worklists that contain the story or tasks from the story.
  • offset (int) – Value to offset results by.
  • limit (int) – Maximum number of results to return.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(Board)

GET /v1/boards/(id)

Retrieve details about one board.

Parameters:
  • id (int) – The ID of the board.
Return type:

Board

POST /v1/boards

Create a new board.

Parameters:
  • board (Board) – A board within the request body.
Return type:

Board

PUT /v1/boards

Modify this board.

Parameters:
  • id (int) – The ID of the board.
  • board (Board) – The new board within the request body.
Return type:

Board

DELETE /v1/boards

Archive this board.

Parameters:
  • id (int) – The ID of the board to be archived.

Permissions

GET /v1/boards/<board_id>/permissions

Get board permissions for the current user.

Parameters:
  • board_id (int) – The ID of the board.
Return type:

list(str)

POST /v1/boards/<board_id>/permissions

Add a new permission to the board.

Parameters:
  • board_id (int) – The ID of the board.
  • permission (dict(str: str)) – The dict to use to create the permission.
Return type:

str

PUT /v1/boards/<board_id>/permissions

Update a permission of the board.

Parameters:
  • board_id (int) – The ID of the board.
  • permission (dict(str: str)) – The new contents of the permission.
Return type:

str

Due Dates

GET /v1/due_dates

Retrieve details about all the due dates.

Parameters:
  • name (str) – The name of the due date.
  • date (datetime) – The date of the due date.
  • board_id (int) – The ID of a board to filter by.
  • worklist_id (int) – The ID of a worklist to filter by.
  • sort_field (str) – The name of the field to sort on.
  • sort_dir (str) – Sort direction for results (asc, desc).
Return type:

list(DueDate)

GET /v1/due_dates/(id)

Retrieve details about one due date.

Parameters:
  • id (int) – The ID of the due date.
Return type:

DueDate

POST /v1/due_dates

Create a new due date.

Parameters:
  • due_date (DueDate) – A due date within the request body.
Return type:

DueDate

PUT /v1/due_dates

Modify a due date.

Parameters:
  • id (int) – The ID of the due date to edit.
  • due_date (DueDate) – The new due date within the request body.
Return type:

DueDate

DELETE /v1/due_dates

Stop associating a due date with a board.

Note: We don’t allow actual deletion of due dates.

Parameters:
  • id (int) – The ID of the due date.
  • board_id (int) – The ID of the board.

Permissions

GET /v1/due_dates/<due_date_id>/permissions

Get due date permissions for the current user.

Parameters:
  • due_date_id (int) – The ID of the due date.
Return type:

list(str)

POST /v1/due_dates/<due_date_id>/permissions

Add a new permission to the due date.

Parameters:
  • due_date_id (int) – The ID of the due date.
  • permission (dict(str: str)) – The dict used to create the permission.
Return type:

str

PUT /v1/due_dates/<due_date_id>/permissions

Update a permission of the due date.

Parameters:
  • due_date_id (int) – The ID of the due date.
  • permission (dict(str: str)) – The new contents of the permission.
Return type:

str

Object model

Story

type Story

The Story is the main element of StoryBoard. It represents a user story (generally a bugfix or a feature) that needs to be implemented. It will be broken down into a series of Tasks, which will each target a specific Project and branch.

Data samples:

Json
{
    "created_at": "2011-11-11T11:11:11",
    "creator_id": 1,
    "description": "We should use Storyboard to manage Storyboard.",
    "id": 425,
    "is_bug": false,
    "status": "active",
    "story_type_id": 1,
    "tags": [
        "t1",
        "t2"
    ],
    "task_statuses": [
        {
            "count": 2,
            "key": "todo"
        }
    ],
    "title": "Use Storyboard to manage Storyboard"
}
XML
b'<value>\n  <title>Use Storyboard to manage Storyboard</title>\n  <description>We should use Storyboard to manage Storyboard.</description>\n  <is_bug>false</is_bug>\n  <creator_id>1</creator_id>\n  <story_type_id>1</story_type_id>\n  <status>active</status>\n  <task_statuses>\n    <item>\n      <key>todo</key>\n      <count>2</count>\n    </item>\n  </task_statuses>\n  <tags>\n    <item>t1</item>\n    <item>t2</item>\n  </tags>\n  <id>425</id>\n  <created_at>2011-11-11T11:11:11</created_at>\n</value>'
creator_id
Type:int

User ID of the Story creator

description
Type:str

A complete description of the goal this story wants to cover.

due_dates
Type:list(int)

List of IDs of Due Dates which are related to this story.

is_bug
Type:bool

Is this a bug or a feature :)

private
Type:bool

Whether or not this story is private.

security
Type:bool

Whether or not this story is security-related.

status
Type:str

The derived status of the story, one of ‘active’, ‘merged’, ‘invalid’

story_type_id
Type:int

ID of story type

tags
Type:list(str)

Tag list assigned to this story.

task_statuses
Type:list(TaskStatusCount)

The summary of each tasks/status.

teams
Type:list(Team)

The set of teams with permission to see this story if it is private.

title
Type:str

A descriptive label for the story, to show in listings.

users
Type:list(User)

The set of users with permission to see this story if it is private.

Task

type Task

A Task represents an actionable work item, targeting a specific Project and a specific branch. It is part of a Story. There may be multiple tasks in a story, pointing to different projects or different branches. Each task is generally linked to a code change proposed in Gerrit.

Data samples:

Json
{
    "assignee_id": 1,
    "branch_id": 1,
    "creator_id": 1,
    "due_dates": [
        1,
        2,
        3
    ],
    "link": "Some notes about the task, this name is bad.",
    "milestone_id": 1,
    "project_id": 1,
    "status": "todo",
    "story_id": 3456,
    "title": "My really important task."
}
XML
b'<value>\n  <title>My really important task.</title>\n  <status>todo</status>\n  <creator_id>1</creator_id>\n  <story_id>3456</story_id>\n  <link>Some notes about the task, this name is bad.</link>\n  <project_id>1</project_id>\n  <assignee_id>1</assignee_id>\n  <branch_id>1</branch_id>\n  <milestone_id>1</milestone_id>\n  <due_dates>\n    <item>1</item>\n    <item>2</item>\n    <item>3</item>\n  </due_dates>\n</value>'
assignee_id
Type:int

The ID of the invidiual to whom this task is assigned.

branch_id
Type:int

The ID of corresponding Branch

creator_id
Type:int

Id of the User who has created this Task

due_dates
Type:list(int)

The IDs of due dates related to this task.

Type:str

A related resource for this task.

milestone_id
Type:int

The ID of corresponding Milestone

project_id
Type:int

The ID of the corresponding Project.

status
Type:Enum(todo, inprogress, invalid, review, merged)

The type of statuses allowed [‘todo’, ‘inprogress’, ‘invalid’, ‘review’, ‘merged’].

story_id
Type:int

The ID of the corresponding Story.

title
Type:str

An optional short label for the task, to show in listings.

Project

type Project

The Storyboard Registry describes the open source world as ProjectGroups and Projects. Each ProjectGroup may be responsible for several Projects. For example, the OpenStack Infrastructure ProjectGroup has Zuul, Nodepool, Storyboard as Projects, among others.

Data samples:

Json
{
    "created_at": "2011-11-11T11:11:11",
    "description": "This is an awesome project.",
    "id": 3,
    "is_active": true,
    "name": "StoryBoard",
    "repo_url": "https://git.openstack.org/openstack-infra/storyboard.git"
}
XML
b'<value>\n  <name>StoryBoard</name>\n  <description>This is an awesome project.</description>\n  <is_active>true</is_active>\n  <repo_url>https://git.openstack.org/openstack-infra/storyboard.git</repo_url>\n  <id>3</id>\n  <created_at>2011-11-11T11:11:11</created_at>\n</value>'
autocreate_branches
Type:bool

This flag means that storyboard will try to create task branches automatically from the branches declared in the code repository.

description
Type:str

Details about the project’s work, highlights, goals, and how to contribute. Use plain text, paragraphs are preserved and URLs are linked in pages.

is_active
Type:bool

Is this an active project, or has it been deleted?

name
Type:string

The Project unique name. This name will be displayed in the URL. At least 3 alphanumeric symbols. Minus and dot symbols are allowed as separators.

repo_url
Type:str

This is a repo link for this project

ProjectGroup

type ProjectGroup

Represents a group of projects.

Data samples:

Json
{
    "created_at": "2011-11-11T11:11:11",
    "id": 1,
    "name": "Infra",
    "title": "Awesome projects"
}
XML
b'<value>\n  <name>Infra</name>\n  <title>Awesome projects</title>\n  <id>1</id>\n  <created_at>2011-11-11T11:11:11</created_at>\n</value>'
name
Type:string

The Project Group unique name. This name will be displayed in the URL. At least 3 alphanumeric symbols. Minus and dot symbols are allowed as separators.

title
Type:str

The full name of the project group, which can contain spaces, special characters, etc.

Comment

type Comment

Any user may leave comments on stories.

Data samples:

Json
{
    "content": "A sample comment body.",
    "created_at": "2011-11-11T11:11:11",
    "id": 5,
    "in_reply_to": 2,
    "is_active": true
}
XML
b'<value>\n  <content>A sample comment body.</content>\n  <is_active>true</is_active>\n  <in_reply_to>2</in_reply_to>\n  <id>5</id>\n  <created_at>2011-11-11T11:11:11</created_at>\n</value>'
content
Type:str

The content of the comment.

in_reply_to
Type:int

The ID of the parent comment, if any.

is_active
Type:bool

Is this an active comment, or has it been deleted?

Timeline event

type TimeLineEvent

An event object should be created each time a story or a task state changes.

Data samples:

Json
{
    "event_info": "{\"story_id\": 100, \"story_title\": \"A story\"}",
    "event_type": "story_created",
    "id": 45543,
    "story_id": 100
}
XML
b'<value>\n  <event_type>story_created</event_type>\n  <event_info>{"story_id": 100, "story_title": "A story"}</event_info>\n  <story_id>100</story_id>\n  <id>45543</id>\n</value>'
author_id
Type:int

The ID of User who has left the comment.

board_id
Type:int

The ID of the corresponding Board.

comment
Type:Comment

The resolved comment.

comment_id
Type:int

The id of a comment linked to this event.

event_info
Type:str

A JSON encoded field with details about the event.

event_type
Type:str

This type should serve as a hint for the web-client when rendering a comment.

story_id
Type:int

The ID of the corresponding Story.

worklist_id
Type:int

The ID of the corresponding Worklist.

Due Date

type DueDate

Represents a due date for tasks/stories.

Data samples:

Json
{
    "assignable": true,
    "count": 0,
    "creator_id": 3,
    "date": "2016-05-30T10:10:00",
    "editable": true,
    "id": 1,
    "name": "A really great deadline",
    "owners": [
        3
    ],
    "private": false,
    "stories": [],
    "tasks": [],
    "users": []
}
XML
b'<value>\n  <name>A really great deadline</name>\n  <date>2016-05-30T10:10:00</date>\n  <private>false</private>\n  <creator_id>3</creator_id>\n  <tasks />\n  <stories />\n  <count>0</count>\n  <owners>\n    <item>3</item>\n  </owners>\n  <users />\n  <editable>true</editable>\n  <assignable>true</assignable>\n  <id>1</id>\n</value>'
assignable
Type:bool

Whether or not the due date is assignable by the request sender.

board_id
Type:int

The ID of a board which contains this due date.

Used by PUT requests adding the due date to a board.

count
Type:int

The number of tasks and stories with this dues date.

creator_id
Type:int

The ID of the user that created the DueDate.

date
Type:datetime

The date of the due date

editable
Type:bool

Whether or not the due date is editable by the request sender.

name
Type:str

The name of the due date.

owners
Type:list(int)

A list of the IDs of the users who can change this date.

private
Type:bool

A flag to identify whether this is a private or public due date.

stories
Type:list(Story)

A list containing all the stories with this due date.

tasks
Type:list(Task)

A list containing all the tasks with this due date.

users
Type:list(int)

A list of the IDs of the users who can assign this date to tasks.

worklist_id
Type:int

The ID of a worklist which contains this due date.

Used by PUT requests adding the due date to a worklist.

Board

type Board

Represents a kanban board made up of worklists.

Data samples:

Json
{
    "archived": false,
    "creator_id": 1,
    "description": "Board for tracking StoryBoard development.",
    "due_dates": [],
    "id": 1,
    "lanes": [
        {
            "board_id": 23,
            "id": 1,
            "list_id": 10,
            "position": 1,
            "worklist": {
                "archived": false,
                "automatic": false,
                "creator_id": 1,
                "filters": [],
                "id": 1,
                "items": [],
                "owners": [
                    1
                ],
                "private": false,
                "title": "My great worklist",
                "users": [
                    2
                ]
            }
        }
    ],
    "owners": [
        1
    ],
    "private": false,
    "team_owners": [
        1,
        2
    ],
    "team_users": [],
    "title": "StoryBoard development",
    "users": []
}
XML
b'<value>\n  <title>StoryBoard development</title>\n  <description>Board for tracking StoryBoard development.</description>\n  <creator_id>1</creator_id>\n  <private>false</private>\n  <archived>false</archived>\n  <lanes>\n    <item>\n      <board_id>23</board_id>\n      <list_id>10</list_id>\n      <worklist>\n        <title>My great worklist</title>\n        <creator_id>1</creator_id>\n        <private>false</private>\n        <archived>false</archived>\n        <automatic>false</automatic>\n        <filters />\n        <owners>\n          <item>1</item>\n        </owners>\n        <users>\n          <item>2</item>\n        </users>\n        <items />\n        <id>1</id>\n      </worklist>\n      <position>1</position>\n      <id>1</id>\n    </item>\n  </lanes>\n  <due_dates />\n  <owners>\n    <item>1</item>\n  </owners>\n  <users />\n  <team_owners>\n    <item>1</item>\n    <item>2</item>\n  </team_owners>\n  <team_users />\n  <id>1</id>\n</value>'
archived
Type:bool

A flag to identify whether or not the board has been archived.

creator_id
Type:int

The ID of the User who created this board.

description
Type:str

The description of the board.

due_dates
Type:list(DueDate)

A list containing the due dates used in this board.

lanes
Type:list(Lane)

A list containing the representions of the lanes in this board.

owners
Type:list(int)

A list of the IDs of the users who have full permissions.

permission_id
Type:int

The ID of the Permission which defines who can edit this board.

private
Type:bool

A flag to identify whether this is a private or public board.

project_id
Type:int

The ID of the Project this board is associated with.

team_owners
Type:list(int)

A list of the IDs of the teams who have full permissions.

team_users
Type:list(int)

A list of the IDs of the teams who can move cards in the board.

title
Type:str

The title of the board.

users
Type:list(int)

A list of the IDs of the users who can move cards in the board.

Worklist

type Worklist

Represents a worklist.

Data samples:

Json
{
    "archived": false,
    "automatic": false,
    "creator_id": 1,
    "filters": [],
    "id": 1,
    "items": [],
    "owners": [
        1
    ],
    "private": false,
    "title": "My great worklist",
    "users": [
        2
    ]
}
XML
b'<value>\n  <title>My great worklist</title>\n  <creator_id>1</creator_id>\n  <private>false</private>\n  <archived>false</archived>\n  <automatic>false</automatic>\n  <filters />\n  <owners>\n    <item>1</item>\n  </owners>\n  <users>\n    <item>2</item>\n  </users>\n  <items />\n  <id>1</id>\n</value>'
archived
Type:bool

A flag to identify whether or not the worklist has been archived.

automatic
Type:bool

A flag to identify whether the contents are obtained by a filter or are stored in the database.

creator_id
Type:int

The ID of the User who created this worklist.

filters
Type:list(WorklistFilter)

A list of filters used if this is an “automatic” worklist.

items
Type:list(WorklistItem)

The items in the worklist.

owners
Type:list(int)

A list of the IDs of the users who have full permissions.

permission_id
Type:int

The ID of the Permission which defines who can edit this worklist.

private
Type:bool

A flag to identify if this is a private or public worklist.

project_id
Type:int

The ID of the Project this worklist is associated with.

team_owners
Type:list(int)

A list of the IDs of the teams who have full permissions.

team_users
Type:list(int)

A list of the IDs of the teams who can move items in the worklist.

title
Type:str

The title of the worklist.

users
Type:list(int)

A list of the IDs of the users who can move items in the worklist.

WorklistItem

type WorklistItem

Represents an item in a worklist.

The item could be either a story or a task.

Data samples:

Json
{
    "archived": false,
    "display_due_date": null,
    "id": 1,
    "item_id": 1,
    "item_type": "story",
    "list_id": 1,
    "list_position": 0
}
XML
b'<value>\n  <list_id>1</list_id>\n  <item_id>1</item_id>\n  <item_type>story</item_type>\n  <list_position>0</list_position>\n  <archived>false</archived>\n  <display_due_date nil="true" />\n  <id>1</id>\n</value>'
archived
Type:bool

Whether or not this item is archived.

display_due_date
Type:int

The ID of the due date displayed on this item.

item_id
Type:int

The ID of the Task or Story for this item.

item_type
Type:str

The type of this item, either “story” or “task”.

list_id
Type:int

The ID of the Worklist this item belongs to.

list_position
Type:int

The position of this item in the Worklist.

resolved_due_date
Type:DueDate

The Due Date displayed on this item.

story
Type:Story

The Story referred to by this list item.

task
Type:Task

The Task referred to by this list item.

WorklistFilter

type WorklistFilter

Represents a set of criteria to filter items using AND.

Data samples:

Json
{
    "filter_criteria": [
        {
            "field": "status",
            "filter_id": 1,
            "negative": true,
            "title": "TaskStatus",
            "value": "merged"
        }
    ],
    "list_id": 1,
    "type": "Task"
}
XML
b'<value>\n  <type>Task</type>\n  <list_id>1</list_id>\n  <filter_criteria>\n    <item>\n      <title>TaskStatus</title>\n      <filter_id>1</filter_id>\n      <negative>true</negative>\n      <value>merged</value>\n      <field>status</field>\n    </item>\n  </filter_criteria>\n</value>'
filter_criteria
Type:list(FilterCriterion)

The list of criteria to apply.

list_id
Type:int

The ID of the Worklist this filter is for.

type
Type:Enum(Story, Task)

The type of objects to filter, Story or Task.

FilterCriterion

type FilterCriterion

Represents a filter used to construct an automatic worklist.

Data samples:

Json
{
    "field": "status",
    "filter_id": 1,
    "negative": true,
    "title": "TaskStatus",
    "value": "merged"
}
XML
b'<value>\n  <title>TaskStatus</title>\n  <filter_id>1</filter_id>\n  <negative>true</negative>\n  <value>merged</value>\n  <field>status</field>\n</value>'
field
Type:str

The field to filter by.

filter_id
Type:int

The ID of the WorklistFilter this criterion is for.

negative
Type:bool

Whether to return all items matching or not matching the criterion.

title
Type:str

The title of the criterion, as displayed in the UI.

value
Type:str

The value to use as a criterion.

User

type User

Represents a user.

Data samples:

Json
{
    "email": "skinnerstinks@springfield.net",
    "full_name": "Bart Simpson",
    "id": 3,
    "is_superuser": true,
    "last_login": "2014-01-01T16:42:00",
    "openid": "https://login.launchpad.net/+id/Abacaba"
}
XML
b'<value>\n  <full_name>Bart Simpson</full_name>\n  <openid>https://login.launchpad.net/+id/Abacaba</openid>\n  <email>skinnerstinks@springfield.net</email>\n  <is_superuser>true</is_superuser>\n  <last_login>2014-01-01T16:42:00</last_login>\n  <id>3</id>\n</value>'
email
Type:str

Email Address.

enable_login
Type:bool

Whether this user is permitted to log in.

full_name
Type:str

Full (Display) name.

is_superuser
Type:bool

Whether or not the user has superuser permissions.

last_login
Type:datetime

Date of the last login.

openid
Type:str

The unique identifier, returned by an OpenId provider

SystemInfo

type SystemInfo

Represents the system information for Storyboard

Data samples:

Json
{
    "version": "338c2d6"
}
XML
b'<value>\n  <version>338c2d6</version>\n</value>'
version
Type:str

The application version.