How to consume ScrumDesk API

ScrumDesk API is built with the support of HAL – the hypertext application language. It is a simple format that gives a consistent and easy way to hyperlink between resources in our API.  It can be easily consumed using open source libraries available for most major programming languages. It’s also simple enough that you can just deal with it as you would any other JSON.

ScrumDesk API is the set of resources represented by URLs. Every URL doesn’t just return data, but it includes also:

  • permissions for the logged user and particular resource (see options: on the picture above),
  • list of additional links and resource available for the resource (related collections, subtasks, relations, comments, etc.

For request use  application/json (Content-Type, Accept)

ScrumDesk API example

Projects accessible for the logged user, the response for https://api.scrumdesk.com/users/XX/projects API request

Authorization (POST)

Authorization token must be included in every API call must either in the header or in the URL link itself.

In HEADER:

https://api.scrumdesk.com/auth

Authorization, Token token=token_value

In URL:

https://api.scrumdesk.com/auth?access_token=token_value

Authorization for custom integrations

It is possible to use project level authorization if you want to create your own integration and would like to access and manage project data without the necessity to authorize project users. Please contact support@scrumdesk.com in this case and request access token for your integration.

Login via email and password

https://api.scrumdesk.com/auth

{ “username”: “”,  “password”: “” }

Output:

  • access_token
  • links
    • link to user

Data model structure simplified

Account

  • Invitation
  • Organization members
  • User

Projects

  • Project membership
  • Project detail
  • Workflow + workflow steps

OKR Desk

  • Okr diagrams
  • Okr nodes
  • Key results

Product Desk

  • Roadmaps
    • Roadmap diagram
    • Roadmap group
    • Roadmap row
    • Roadmap lane
    • Roadmap box
    • Milestones

Scrum board

  • Release
  • Sprint
  • Themes
  • Epics
  • Backlog item types
  • Task types
  • Custom fields
  • Colors
  • Backlog Items
  • Tasks
    • Worklogs
    • Board items that represent visual aspects of cards

Retro Desk

  • Retro idea
  • Retro idea category
  • Retro idea vote

RCA Desk

  • RCA node
  • RCA link
  • Retro technique

Common

  • Constants
  • Comments related to either tasks or backlog items
  • History
  • Attachments
  • Notifications
  • Relations

Backlog Items

Project details contain the list of backlog items referenced in the links section. The user must be either product owner or Scrum master role in the project.

API Endpoints Reference

PrefixVerbURI Pattern
authPOST/auth
GET/auth
DELETE/auth
registrationPOST/registration
registration_oauthPOST/registration/oauth
reset_passwordPOST/users/reset_password
user_projectsGET/users/:user_id/projects
POST/users/:user_id/projects
current_userGET/current_user
PROJECT
multisearch_projectGET/projects/:id/multisearch
project_project_initializationsGET/projects/:project_id/init
velocity_charts_projectGET/projects/:id/velocity_charts
cumulative_chart_projectGET/projects/:id/cumulative_chart
capacity_charts_projectGET/projects/:id/capacity_charts
value_chart_projectGET/projects/:id/value_chart
complexity_time_chart_projectGET/projects/:id/complexity_time_chart
value_vs_effort_chart_projectGET/projects/:id/value_vs_effort_chart
work_by_task_types_chart_projectGET/projects/:id/work_by_task_types_chart
work_by_backlog_items_types_chart_projectGET/projects/:id/work_by_backlog_items_types_chart
spent_vs_estimated_chart_projectGET/projects/:id/spent_vs_estimated_chart
control_chart_projectGET/projects/:id/control_chart
import_projectPOST/projects/:id/import
project_user_settingGET/project_user_settings/:id
PATCH/project_user_settings/:id
PUT/project_user_settings/:id
EPIC
epic_archivePOST/epics/:epic_id/archive
epic_restorePOST/epics/:epic_id/restore
reorder_epicPOST/epics/:id/reorder
copy_epicPOST/epics/:id/copy
move_epicPOST/epics/:id/move
ancestors_epicGET/epics/:id/ancestors
project_epicsGET/projects/:project_id/epics
POST/projects/:project_id/epics
new_project_epicGET/projects/:project_id/epics/new
edit_epicGET/epics/:id/edit
epicGET/epics/:id
PATCH/epics/:id
PUT/epics/:id
DELETE/epics/:id
RELEASE
burndown_releaseGET/releases/:id/burndown
burndown_report_releaseGET/releases/:id/burndown_report
stats_releaseGET/releases/:id/stats
event_releasePOST/releases/:id/event
archive_releasePOST/releases/:id/archive
restore_releasePOST/releases/:id/restore
project_releasesGET/projects/:project_id/releases
POST/projects/:project_id/releases
new_project_releaseGET/projects/:project_id/releases/new
edit_releaseGET/releases/:id/edit
releaseGET/releases/:id
PATCH/releases/:id
PUT/releases/:id
DELETE/releases/:id
SPRINT
burndown_sprintGET/sprints/:id/burndown
stats_sprintGET/sprints/:id/stats
event_sprintPOST/sprints/:id/event
archive_sprintPOST/sprints/:id/archive
restore_sprintPOST/sprints/:id/restore
project_sprintsGET/projects/:project_id/sprints
POST/projects/:project_id/sprints
new_project_sprintGET/projects/:project_id/sprints/new
edit_sprintGET/sprints/:id/edit
sprintGET/sprints/:id
PATCH/sprints/:id
PUT/sprints/:id
DELETE/sprints/:id
project_sprint_capacitiesGET/projects/:project_id/sprint_capacities
sprint_capacityGET/sprint_capacities/:id
PATCH/sprint_capacities/:id
PUT/sprint_capacities/:id
project_themesGET/projects/:project_id/themes
POST/projects/:project_id/themes
new_project_themeGET/projects/:project_id/themes/new
THEME
edit_themeGET/themes/:id/edit
themeGET/themes/:id
PATCH/themes/:id
PUT/themes/:id
DELETE/themes/:id
BACKLOG ITEM
create_clone_backlog_itemPOST/backlog_items/:id/create_clone
split_backlog_itemPOST/backlog_items/:id/split
epic_reorder_backlog_itemPOST/backlog_items/:id/epic_reorder
search_project_backlog_itemsGET/projects/:project_id/backlog_items/search
removed_from_sprint_project_backlog_itemsGET/projects/:project_id/backlog_items/removed_from_sprint
reorder_backlog_itemPOST/backlog_items/:id/reorder
multi_update_project_backlog_itemsPATCH/projects/:project_id/backlog_items
multi_destroy_project_backlog_itemsDELETE/projects/:project_id/backlog_items
move_backlog_itemPOST/backlog_items/:id/move
export_project_backlog_itemsPOST/projects/:project_id/backlog_items/export
convert_backlog_itemPOST/backlog_items/:id/convert
project_backlog_itemsGET/projects/:project_id/backlog_items
POST/projects/:project_id/backlog_items
new_project_backlog_itemGET/projects/:project_id/backlog_items/new
edit_backlog_itemGET/backlog_items/:id/edit
backlog_itemGET/backlog_items/:id
PATCH/backlog_items/:id
PUT/backlog_items/:id
DELETE/backlog_items/:id
TASK
create_clone_taskPOST/tasks/:id/create_clone
reorder_taskPOST/tasks/:id/reorder
export_project_tasksPOST/projects/:project_id/tasks/export
convert_taskPOST/tasks/:id/convert
project_tasksGET/projects/:project_id/tasks
POST/projects/:project_id/tasks
new_project_taskGET/projects/:project_id/tasks/new
edit_taskGET/tasks/:id/edit
taskGET/tasks/:id
PATCH/tasks/:id
PUT/tasks/:id
DELETE/tasks/:id
TASK TYPE
project_task_typesGET/projects/:project_id/task_types
POST/projects/:project_id/task_types
new_project_task_typeGET/projects/:project_id/task_types/new
edit_task_typeGET/task_types/:id/edit
task_typeGET/task_types/:id
PATCH/task_types/:id
PUT/task_types/:id
DELETE/task_types/:id
ATTACHMENT
download_file_attachmentGET/attachments/:id/download_file
project_attachmentsGET/projects/:project_id/attachments
POST/projects/:project_id/attachments
new_project_attachmentGET/projects/:project_id/attachments/new
edit_attachmentGET/attachments/:id/edit
attachmentGET/attachments/:id
PATCH/attachments/:id
PUT/attachments/:id
DELETE/attachments/:id
RELATION
project_relationsGET/projects/:project_id/relations
POST/projects/:project_id/relations
new_project_relationGET/projects/:project_id/relations/new
edit_relationGET/relations/:id/edit
relationGET/relations/:id
PATCH/relations/:id
PUT/relations/:id
DELETE/relations/:id
COMMENT
project_commentsGET/projects/:project_id/comments
POST/projects/:project_id/comments
new_project_commentGET/projects/:project_id/comments/new
edit_commentGET/comments/:id/edit
commentGET/comments/:id
PATCH/comments/:id
PUT/comments/:id
DELETE/comments/:id
HISTORY
project_history_changesGET/projects/:project_id/history_changes
history_changeGET/history_changes/:id
TASK LOG/WORKLOG
report_project_task_logsGET/projects/:project_id/task_logs/report
project_task_logsGET/projects/:project_id/task_logs
POST/projects/:project_id/task_logs
new_project_task_logGET/projects/:project_id/task_logs/new
edit_task_logGET/task_logs/:id/edit
task_logGET/task_logs/:id
PATCH/task_logs/:id
PUT/task_logs/:id
DELETE/task_logs/:id
BACKLOG ITEM TEMPLATE
project_backlog_item_templatesGET/projects/:project_id/backlog_item_templates
POST/projects/:project_id/backlog_item_templates
new_project_backlog_item_templateGET/projects/:project_id/backlog_item_templates/new
edit_backlog_item_templateGET/backlog_item_templates/:id/edit
backlog_item_templateGET/backlog_item_templates/:id
PATCH/backlog_item_templates/:id
PUT/backlog_item_templates/:id
DELETE/backlog_item_templates/:id
TASK TEMPLATE
project_task_templatesGET/projects/:project_id/task_templates
POST/projects/:project_id/task_templates
new_project_task_templateGET/projects/:project_id/task_templates/new
edit_task_templateGET/task_templates/:id/edit
task_templateGET/task_templates/:id
PATCH/task_templates/:id
PUT/task_templates/:id
DELETE/task_templates/:id
BOARD
project_boardsGET/projects/:project_id/boards
boardGET/boards/:id
positions_project_board_itemsPATCH/projects/:project_id/board_items/positions
project_board_itemsGET/projects/:project_id/board_items
board_itemGET/board_items/:id
PATCH/board_items/:id
PUT/board_items/:id
PROJECT MEMBERSHIP
project_project_membershipsGET/projects/:project_id/project_memberships
POST/projects/:project_id/project_memberships
new_project_project_membershipGET/projects/:project_id/project_memberships/new
edit_project_membershipGET/project_memberships/:id/edit
project_membershipGET/project_memberships/:id
PATCH/project_memberships/:id
PUT/project_memberships/:id
DELETE/project_memberships/:id
project_project_membersGET/projects/:project_id/project_members
project_project_invitationsGET/projects/:project_id/project_invitations
POST/projects/:project_id/project_invitations
project_invitationGET/project_invitations/:id
DELETE/project_invitations/:id
PROJECT
project_project_constantsGET/projects/:project_id/constants
POST/projects/:project_id/constants
new_project_project_constantGET/projects/:project_id/constants/new
edit_project_project_constantGET/projects/:project_id/constants/:id/edit
project_project_constantGET/projects/:project_id/constants/:id
PATCH/projects/:project_id/constants/:id
PUT/projects/:project_id/constants/:id
DELETE/projects/:project_id/constants/:id
project_project_tagsGET/projects/:project_id/tags
project_workflowGET/projects/:project_id/workflow
RETRO IDEA CATEGORY
project_retro_idea_categoriesGET/projects/:project_id/retro_idea_categories
POST/projects/:project_id/retro_idea_categories
new_project_retro_idea_categoryGET/projects/:project_id/retro_idea_categories/new
edit_retro_idea_categoryGET/retro_idea_categories/:id/edit
retro_idea_categoryGET/retro_idea_categories/:id
PATCH/retro_idea_categories/:id
PUT/retro_idea_categories/:id
DELETE/retro_idea_categories/:id
RETRO IDEA VOTE
retro_idea_voteGET/retro_idea_votes/:id
PATCH/retro_idea_votes/:id
PUT/retro_idea_votes/:id
reorder_retro_ideaPOST/retro_ideas/:id/reorder
project_retro_ideasGET/projects/:project_id/retro_ideas
POST/projects/:project_id/retro_ideas
new_project_retro_ideaGET/projects/:project_id/retro_ideas/new
edit_retro_ideaGET/retro_ideas/:id/edit
retro_ideaGET/retro_ideas/:id
PATCH/retro_ideas/:id
PUT/retro_ideas/:id
DELETE/retro_ideas/:id
RETRO IDEA  TECHNIQUE
project_retro_techniquesGET/projects/:project_id/retro_techniques
project_retro_idea_templatesGET/projects/:project_id/retro_idea_templates
CUSTOM FIELD
project_custom_field_templatesGET/projects/:project_id/custom_field_templates
POST/projects/:project_id/custom_field_templates
new_project_custom_field_templateGET/projects/:project_id/custom_field_templates/new
edit_custom_field_templateGET/custom_field_templates/:id/edit
custom_field_templateGET/custom_field_templates/:id
PATCH/custom_field_templates/:id
PUT/custom_field_templates/:id
DELETE/custom_field_templates/:id
project_custom_fieldsGET/projects/:project_id/custom_fields
POST/projects/:project_id/custom_fields
new_project_custom_fieldGET/projects/:project_id/custom_fields/new
edit_custom_fieldGET/custom_fields/:id/edit
custom_fieldGET/custom_fields/:id
PATCH/custom_fields/:id
PUT/custom_fields/:id
DELETE/custom_fields/:id
project_custom_fields_valuesGET/projects/:project_id/custom_fields_values
NOTIFICATION
seen_notificationPOST/notifications/:id/seen
unseen_notificationPOST/notifications/:id/unseen
seen_all_project_notificationsPOST/projects/:project_id/notifications/seen_all
project_notificationsGET/projects/:project_id/notifications
notificationGET/notifications/:id
WORKFLOW STEP
reorder_workflow_stepPOST/workflow_steps/:id/reorder
project_workflow_stepsGET/projects/:project_id/workflow_steps
POST/projects/:project_id/workflow_steps
workflow_stepGET/workflow_steps/:id
PATCH/workflow_steps/:id
PUT/workflow_steps/:id
DELETE/workflow_steps/:id
RCA DIAGRAM
project_rca_diagramsGET/projects/:project_id/rca/diagrams
POST/projects/:project_id/rca/diagrams
rca_diagramGET/rca/diagrams/:id
PATCH/rca/diagrams/:id
PUT/rca/diagrams/:id
DELETE/rca/diagrams/:id
project_rca_nodesGET/projects/:project_id/rca/nodes
POST/projects/:project_id/rca/nodes
rca_nodeGET/rca/nodes/:id
PATCH/rca/nodes/:id
PUT/rca/nodes/:id
DELETE/rca/nodes/:id
project_rca_linksGET/projects/:project_id/rca/links
POST/projects/:project_id/rca/links
rca_linkGET/rca/links/:id
PATCH/rca/links/:id
PUT/rca/links/:id
DELETE/rca/links/:id
project_rca_categoriesGET/projects/:project_id/rca/categories
OKR DIAGRAM
project_okr_diagramsGET/projects/:project_id/okr/diagrams
POST/projects/:project_id/okr/diagrams
okr_diagramGET/okr/diagrams/:id
PATCH/okr/diagrams/:id
PUT/okr/diagrams/:id
DELETE/okr/diagrams/:id
project_okr_nodesGET/projects/:project_id/okr/nodes
POST/projects/:project_id/okr/nodes
okr_nodeGET/okr/nodes/:id
PATCH/okr/nodes/:id
PUT/okr/nodes/:id
DELETE/okr/nodes/:id
project_okr_node_key_resultsGET/projects/:project_id/okr/node_key_results
POST/projects/:project_id/okr/node_key_results
okr_node_key_resultGET/okr/node_key_results/:id
PATCH/okr/node_key_results/:id
PUT/okr/node_key_results/:id
DELETE/okr/node_key_results/:id
project_okr_linksGET/projects/:project_id/okr/links
POST/projects/:project_id/okr/links
okr_linkGET/okr/links/:id
PATCH/okr/links/:id
PUT/okr/links/:id
DELETE/okr/links/:id
project_okr_categoriesGET/projects/:project_id/okr/categories
ROADMAP
project_rmp_roadmapsGET/projects/:project_id/rmp/roadmaps
POST/projects/:project_id/rmp/roadmaps
rmp_roadmapGET/rmp/roadmaps/:id
PATCH/rmp/roadmaps/:id
PUT/rmp/roadmaps/:id
DELETE/rmp/roadmaps/:id
reorder_rmp_groupPOST/rmp/groups/:id/reorder
project_rmp_groupsGET/projects/:project_id/rmp/groups
POST/projects/:project_id/rmp/groups
rmp_groupGET/rmp/groups/:id
PATCH/rmp/groups/:id
PUT/rmp/groups/:id
DELETE/rmp/groups/:id
reorder_rmp_lanePOST/rmp/lanes/:id/reorder
project_rmp_lanesGET/projects/:project_id/rmp/lanes
POST/projects/:project_id/rmp/lanes
rmp_laneGET/rmp/lanes/:id
PATCH/rmp/lanes/:id
PUT/rmp/lanes/:id
DELETE/rmp/lanes/:id
reorder_rmp_rowPOST/rmp/rows/:id/reorder
project_rmp_rowsGET/projects/:project_id/rmp/rows
POST/projects/:project_id/rmp/rows
rmp_rowGET/rmp/rows/:id
DELETE/rmp/rows/:id
project_rmp_boxesGET/projects/:project_id/rmp/boxes
POST/projects/:project_id/rmp/boxes
rmp_boxGET/rmp/boxes/:id
PATCH/rmp/boxes/:id
PUT/rmp/boxes/:id
DELETE/rmp/boxes/:id
project_rmp_milestonesGET/projects/:project_id/rmp/milestones
POST/projects/:project_id/rmp/milestones
rmp_milestoneGET/rmp/milestones/:id
PATCH/rmp/milestones/:id
PUT/rmp/milestones/:id
DELETE/rmp/milestones/:id
PROJECT
archive_projectPOST/projects/:id/archive
restore_projectPOST/projects/:id/restore
projectsPOST/projects
projectGET/projects/:id
PATCH/projects/:id
PUT/projects/:id
DELETE/projects/:id
USER ACCOUNT
user_accountsGET/users/:user_id/accounts
POST/users/:user_id/accounts
account_account_initializationsGET/accounts/:account_id/init
activate_account_membershipPOST/account_memberships/:id/activate
deactivate_account_membershipPOST/account_memberships/:id/deactivate
account_account_membershipsGET/accounts/:account_id/account_memberships
POST/accounts/:account_id/account_memberships
new_account_account_membershipGET/accounts/:account_id/account_memberships/new
edit_account_membershipGET/account_memberships/:id/edit
account_membershipGET/account_memberships/:id
PATCH/account_memberships/:id
PUT/account_memberships/:id
DELETE/account_memberships/:id
INVITATION
accept_invitationPOST/invitations/:id/accept
reject_invitationPOST/invitations/:id/reject
account_invitationsGET/accounts/:account_id/invitations
POST/accounts/:account_id/invitations
invitationGET/invitations/:id
DELETE/invitations/:id
USER
account_usersGET/accounts/:account_id/users
userGET/users/:id
PATCH/users/:id
PUT/users/:id
DELETE/users/:id
archive_accountPOST/accounts/:id/archive
restore_accountPOST/accounts/:id/restore
accountGET/accounts/:id
PATCH/accounts/:id
PUT/accounts/:id
DELETE/accounts/:id
CONSTANT
constantsGET/constants