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:

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`)

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`

GET /v1/projects/search¶

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:

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. 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(`ProjectGroup`)

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.
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(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:

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`)

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.

GET /v1/stories/search¶

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:

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`)

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:

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`)

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:

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`)

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:

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`)

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.

GET /v1/tasks/search¶

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:

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`)

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`

GET /v1/users/search¶

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.

link¶

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

{
    "config": {
        "enable_editable_comments": true
    },
    "version": "338c2d6"
}

XML

b'<value>\n  <config>\n    <item>\n      <key>enable_editable_comments</key>\n      <value>true</value>\n    </item>\n  </config>\n  <version>338c2d6</version>\n</value>'

config¶

Type:	dict(str: bool)

Information about enabled features from configuration.

version¶

Type:	str

The application version.

V1 Web API

V1 Web API¶

API¶

Projects¶

Project Groups¶

Stories¶

Comments and Timeline events¶

Tasks¶

Branches¶

Milestones¶

Tags¶

Subscriptions¶

Users¶

Teams¶

User Preferences¶

System Info¶

User Tokens¶

Worklists¶

Filters¶

Items¶

Permissions¶

Boards¶

Permissions¶

Due Dates¶

Permissions¶

Object model¶

Story¶

Task¶

Project¶

ProjectGroup¶

Comment¶

Timeline event¶

Due Date¶

Board¶

Worklist¶

WorklistItem¶

WorklistFilter¶

FilterCriterion¶

User¶

SystemInfo¶

storyboard-api 1.1.1.dev8

Page Contents