Overview

Introduction

The Scrumwise API allows you to programmatically access and modify your data in Scrumwise. It’s a collection of methods that you can invoke using straightforward HTTP POST requests. Results are returned in JSON format.

API keys

You authenticate to the API by providing an API key. You can create and manage your API keys in the settings in Scrumwise. You must be administrator in Scrumwise to do this.

To create an API key, go to the "Your company account" tab in the settings. In the "Settings" page, find the API keys section, and click "Add an API key". When you’ve created the key, you can get the API key string to use in your requests by opening the popup dialog for the key.

You can have multiple keys and use them for different purposes. You can optionally give each key a name to remember what it is used for.

Note: An API key gives full access to all data in your company account, so make sure to keep them secret. To revoke a key, delete it.

Requests

To invoke a method in the API, make an HTTP POST request to this URL: 

https://api.scrumwise.com/service/api/v1/<method name>

You can see the available methods here.

Here is an example that adds a new backlog item, by invoking the addBacklogItem method using the command-line tool curl: 

curl https://api.scrumwise.com/service/api/v1/addBacklogItem -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d projectID=729-11230-1
  -d "name=Example backlog item 1"

You must always use HTTPS. Attempts to use HTTP will receive a redirection response.

All requests must authenticate using HTTP Basic authentication. As username, provide the email address of a user in your account that the request is made on behalf of. As password, provide an API key.

The user that you specify in the authentication determines the permissions that you have in the request. Also, if your request modifies any data, that user will appear in Scrumwise as the person that made the modification.

Parameters to methods must be passed as POST parameters, in URL-encoded query string format. This is the standard format used by an HTML form that uses POST (in other words application/x-www-form-urlencoded). Remember to URL encode each parameter value.

A parameter that is optional can be left out. If left out, the parameter will default to the value that means none, typically null or -1.

To explicitly specify null as a parameter value, use the string "null" (without the quotes). This string is always treated as meaning null. But you can typically leave out the parameter instead.

All names of methods, objects, properties, enumerations, etc. are case-sensitive in the API.

Results

If a method invocation succeeds, you will receive the HTTP response code 200 OK, and a Result object in JSON format.

Here’s an example result from the addBacklogItem method: 

{
  "objectType" : "Result",
  "dataVersion" : 50758,
  "result" : "729-0-69282"
}

A Result object has these three properties:

objectType - string

The type of the object, always Result.

dataVersion - integer

This is the version number that your data had when the result was created. The data in your account has a version number that is increased whenever any change is made to the data. Thus, the data version uniquely identifies the exact state of your data when the result was created.

result - (Type depends on the method)

The result itself, as specified for the method. This is either a primitive type, an object, or an array of objects. In the example above, it’s the id of the new backlog item. You can see the objects used in the API here.

Errors

If a method invocation fails, you will receive an HTTP response code in the 4xx or 5xx ranges, and an Error object in JSON format.

Here’s an example of an error response: 

{
  "objectType" : "Error",
  "errorID" : "ObjectNotFound",
  "errorMessage" : "There is no project with the id 729-110-2."
}

An Error object has these three properties:

objectType - string

The type of the object, always Error.

errorID - string

A string that identifies the type of error, for example ObjectNotFound. You can see the possible error ids here.

errorMessage - string

An error message.

Optional properties in results

Many of the objects that can be returned from method invocations have optional properties. These properties are returned as null unless you explicitly specify in the request that you would like the properties to be included. This way, you can control the size of the response, and avoid getting data that you don’t need.

To include optional properties, specify them as a comma-separated list of property names in a parameter named includeProperties. A property should be prefixed with the name of the object, for example BacklogItem.comments.

We expect that you only include optional properties if you need them, to avoid putting unnecessary load on the Scrumwise servers.

Getting your data

To retrieve data from your account, you always use the getData method. You can select which data to retrieve using the includeProperties parameter. If you include all optional properties in all objects, you will retrieve all of the data in your account in a single request. But don’t retrieve more data than you need.

Here’s an example that invokes getData and includes the backlog items in each project, and the tasks in each backlog item, in the result: 

curl https://api.scrumwise.com/service/api/v1/getData -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d "includeProperties=Project.backlogItems,BacklogItem.tasks"

And here’s the result: 

{
  "objectType" : "Result",
  "dataVersion" : 50759,
  "result" : {
    "objectType" : "Data",
    "persons" : null,
    "deletedPersons" : null,
    "projects" : [ {
      "objectType" : "Project",
      "id" : "729-11230-1",
      "externalID" : null,
      "name" : "Project 1",
      "description" : null,
      "link" : null,
      "status" : "Active",
      "roughEstimateUnit" : "Points",
      "detailedEstimateUnit" : "Days",
      "timeTrackingUnit" : "Hours",
      "checklists" : null,
      "comments" : null,
      "attachments" : null,
      "customFields" : null,
      "tags" : null,
      "productOwnerIDs" : [ "729-334-1" ],
      "stakeholderIDs" : [ "729-4151-1", "729-8107-6" ],
      "teams" : null,
      "messages" : null,
      "backlogs" : null,
      "backlogItems" : [ {
        "objectType" : "BacklogItem",
        "id" : "729-11304-21",
        "externalID" : null,
        "itemNumber" : 214,
        "projectID" : "729-11230-1",
        "parentEpicID" : null,
        "backlogListID" : "729-15220-532",
        "name" : "Backlog item 1",
        "description" : null,
        "link" : null,
        "priority" : null,
        "type" : "Feature",
        "color" : "Blue",
        "creatorID" : "729-3232-553",
        "creationDate" : 1547836680000,
        "bugState" : null,
        "reproducible" : null,
        "resolution" : null,
        "releaseID" : null,
        "status" : "New",
        "toDoDate" : null,
        "inProgressDate" : null,
        "toTestDate" : null,
        "doneDate" : null,
        "roughEstimate" : -1.0,
        "estimate" : -1.0,
        "usedTime" : -1.0,
        "remainingWork" : -1.0,
        "sprintID" : null,
        "teamID" : null,
        "boardID" : null,
        "boardColumnID" : null,
        "isArchivedInBoard" : false,
        "assignedPersonIDs" : [ ],
        "dueDate" : null,
        "customFieldValues" : null,
        "tagIDs" : [ ],
        "checklists" : null,
        "comments" : null,
        "attachments" : null,
        "timeEntries" : null,
        "commits" : null,
        "tasks" : [ {
          "objectType" : "Task",
          "id" : "729-11304-28",
          "externalID" : null,
          "taskNumber" : 532,
          "projectID" : "729-11230-1",
          "backlogItemID" : "729-11304-21",
          "name" : "Task 1",
          "description" : null,
          "link" : null,
          "color" : "Blue",
          "creationDate" : 1547836680000,
          "status" : "To do",
          "toDoDate" : 1547836680000,
          "inProgressDate" : null,
          "toTestDate" : null,
          "doneDate" : null,
          "boardColumnID" : null,
          "estimate" : -1.0,
          "usedTime" : -1.0,
          "remainingWork" : -1.0,
          "assignedPersonIDs" : [ ],
          "dueDate" : null,
          "customFieldValues" : null,
          "tagIDs" : [ ],
          "checklists" : null,
          "comments" : null,
          "attachments" : null,
          "timeEntries" : null,
          "commits" : null
        }, ... ],
        "childBacklogItems" : [ ]
      }, ... ],
      "releases" : null,
      "sprints" : null,
      "boards" : null,
      "retrospectives" : null,
      "files" : null,
      "relationships" : null                    
    }, ... ]
  }
}

The data that you receive from getData is always mutually consistent. It represents your data at a single point in time, identified by the data version that is included in the result.

Polling for changes

You can poll for changes in your data by invoking the getDataVersion method. It returns the current data version of your data. If the data version hasn’t changed since the last time you checked, you know that your data hasn’t changed either.

Here’s an example of invoking getDataVersion: 

curl https://api.scrumwise.com/service/api/v1/getDataVersion -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
{
  "objectType" : "Result",
  "dataVersion" : 50785,
  "result" : 50785
}

Note that the data version is returned both in the dataVersion property, and as the integer result in the result property.

We expect that you don’t poll for changes more often than you need, to avoid putting unnecessary load on the Scrumwise servers. If you need to poll more often than once every minute, please contact us first at support@scrumwise.com, to avoid that your API access is turned off.

Limits

The API has various usage limits to prevent that an API client puts too much load on the Scrumwise servers or behaves in undesired ways.

In general, we expect that you show good behaviour and avoid putting more load on the Scrumwise servers than you need.

Here are some guidelines for good behaviour:

  • Don’t poll for changes more often than about once per minute.
  • Don’t make other requests more frequently than you reasonably need.
  • Don’t retrieve more data than you need. Include only the optional properties that you need.
  • Retrieve your data in as few requests as possible. For example, instead of looping through your projects and making a getData request for each project, we prefer that you retrieve those projects in a single getData request.
  • Don’t make unnecessary updates to your data in Scrumwise, such as repeatedly setting a property to a value that it already has.
  • Don’t make multiple concurrent requests unless you have a good reason. Don’t do it to try to increase your throughput.

If you run into any limits or feel constrained, please contact us at support@scrumwise.com.

Changes to the API

If we make significant backwards-incompatible changes to the API, we will release a new major version of the API.

Each major API version will have its own request URL, and previous major versions will continue to be available.

We will make the following changes to the API as minor versions (so, without changing the request URL):

  • Add new properties in the objects in the API, such as adding a new property in BacklogItem.
  • Add new possible values in properties that are enumerations, such as adding a new possible status in BacklogItem.status.
  • Add new object types, such as adding a new property in Project containing an array of objects of a new type.
  • Add new methods.

Therefore, when parsing the JSON that you receive from a request, make sure to ignore unknown properties and object types, to avoid that your code breaks if we add a new property or object type. And make sure to handle unknown enumeration values (for example, by parsing them to an "Unknown" enumeration value at your end).

You can see the API versions and changes here.

More Info

Charsets

Your requests can use any standard charset, if you specify the charset in the Content-Type header. The API defaults to UTF-8 if you don’t specify a charset.

In the HTTP Basic authentication, always use UTF-8 when encoding the username and password string to bytes before the Base-64 encoding.

The responses from the API are always in UTF-8.

Line breaks

Your requests can use LF or CR+LF as line breaks. The responses from the API always use LF inside JSON string values, encoded as "\n", and CR+LF outside of JSON string values, such as for pretty-printing the JSON.

Compression

To save bandwidth, you can enable compression of the responses from the API by specifying an Accept‑Encoding header in your requests, for example Accept‑Encoding: gzip, deflate. Note that this requires that your HTTP library supports compression.

Linking to objects in other tools

If you are using the API to synchronize your data in Scrumwise with data in another tool, it is often useful to keep track of exactly which objects in Scrumwise correspond to which objects in the other tool.

Most objects in Scrumwise have a property named externalID that you can use for that. In this property, you can store the id that the corresponding object has in the other tool. This way, you can always find the matching objects, without relying on their names or other information.

The externalID property can contain any non-empty string up to 255 characters, or be null. The string must be unique among all objects of that object type in your Scrumwise account.

You can set the external id when creating objects via the API, and you can set it on existing objects using the setter methods.

Avoiding duplicate requests

The API has a mechanism to avoid duplicate requests. A duplicate request can happen if a response gets lost due to a network problem, and you then repeat the same request. You can then, for example, end up creating duplicate copies of an object.

To avoid duplicate requests, here is what you do. Before making a request, generate a unique request id for that request. The request id can be any string up to 255 characters, but must be known to be unique among all request ids that you use with that particular API key. A good approach is to generate a GUID/UUID.

Then, specify the request id in a parameter named requestID in the request. If you don’t get a response from the request and need to retry it, specify the same request id in the repeated attempts.

When receiving a request with a requestID parameter, the API will check if a request has already been successfully executed with that request id. If so, it will abort the request and return an error response to you. The error response will have the error id RequestAlreadyExecuted.

Here’s an example: 

curl https://api.scrumwise.com/service/api/v1/addBacklogItem -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d projectID=729-11230-1
  -d "name=Example backlog item 2"
  -d requestID=550e8400-e29b-41d4-a716-446655440000
{
  "objectType" : "Error",
  "errorID" : "RequestAlreadyExecuted",
  "errorMessage" : "A request with this request id has already been executed successfully."
}

If you get this error response, you know that the request has been executed successfully in a previous attempt, and can stop making more attempts.

You can use the requestID parameter in all methods in the API except getData and getDataVersion.

Avoiding edit conflicts

When you make a sequence of requests to the API, keep in mind that your data may change between the requests, because users in your account may be editing the data at the same time.

In some cases, it’s important to know for sure that no changes have occurred since a previous request that you made. You can achieve this by specifying a required data version in a parameter named requiredDataVersion.

If the API receives a request where the data version in the requiredDataVersion parameter is different from the current data version of your data, the API will abort the request and return an error response to you. The error response will have the error id RequiredDataVersionNotMatching.

Here’s an example: 

curl https://api.scrumwise.com/service/api/v1/addBacklogItem -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d projectID=729-11230-1
  -d "name=Example backlog item 3"
  -d requiredDataVersion=50786
{
  "objectType" : "Error",
  "errorID" : "RequiredDataVersionNotMatching",
  "errorMessage" : "The current data version (50787) does not match the required data version (50786) that you have specified."
}

You can use the requiredDataVersion parameter in all methods in the API except getDataVersion.

Remember that the data version will change when you make a request that modifies your data. Therefore, when you’re making a sequence of requests, you should typically use the resulting data version from one request as the required data version in the next request.

Methods

Attachment methods

addAttachment

Adds an attachment on another object.

Parameters

externalID - string

The external id of the attachment, or null if none. Must be unique among all attachments in your account.

ownerObjectType - string

The object type of the object to add the attachment on. Can be Project, Message, Release, Sprint, BacklogItem, Task, Retrospective, or RetrospectiveCard.

ownerObjectID - string

The id of the object to add the attachment on.

name - string

The name of the attachment, or null if none.

description - string

The description of the attachment, or null if none.

fileName - string

The file name of the attachment, or null if none.

fileContents - string

The file contents, encoded in Base64 format.

index - integer

The index to add the attachment at in the list of attachments in the owner object, or -1 to add the attachment at the end of the list.

Requirements

You must specify either a name (in the name parameter) or a file name (in the fileName parameter), or both.

Result

The id of the new attachment, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addAttachment -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=AT4090223
  -d ownerObjectType=BacklogItem
  -d ownerObjectID=729-0-69327
  -d "name=An example attachment."
  -d "description=An example description."
  -d fileName=Example.txt
  -d fileContents=TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ...
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 50921,
  "result" : "729-0-49832"
}

getAttachmentFileContents

Returns the file contents of an attachment.

Parameters

attachmentID - string

The id of the attachment.

Result

The file contents, encoded in Base64 format.

Example

curl https://api.scrumwise.com/service/api/v1/getAttachmentFileContents
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d attachmentID=729-11304-39
{
  "objectType" : "Result",
  "dataVersion" : 53475,
  "result" : "QmFzZTY0IGlzIGEgZ3JvdXAgb2Ygc2ltaWxhciBiaW5hcnktd..."
}

setAttachmentExternalID

Sets the external id of an attachment.

Parameters

attachmentID - string

The id of the attachment.

externalID - string

The new external id of the attachment, or null if none. Must be unique among all attachments in your account.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/setAttachmentExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d attachmentID=729-11304-39
  -d externalID=AT54673349
{
  "objectType" : "Result",
  "dataVersion" : 50792,
  "result" : null
}

Backlog methods

setBacklogExternalID

Sets the external id of a backlog.

Parameters

backlogID - string

The id of the backlog.

externalID - string

The new external id of the backlog, or null if none. Must be unique among all backlogs in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogID=729-24233-261
  -d externalID=B30983
{
  "objectType" : "Result",
  "dataVersion" : 56248,
  "result" : null
}

Backlog item methods

addBacklogItem

Adds a new backlog item.

Parameters

externalID - string

The external id of the backlog item, or null if none. Must be unique among all backlog items in your account.

projectID - string

The id of the project to add the backlog item in.

parentEpicID - string

The id of the epic to add the backlog item in, or null if the backlog item should not be added to an epic.

backlogListID - string

The id of the backlog list to add the backlog item in, or null to add the backlog item in the first backlog list in the first backlog in the project.

name - string

The name of the backlog item.

description - string

The description of the backlog item, or null if none.

link - string

The link URL of the backlog item, or null if none.

priority - string

The priority of the backlog item, or null if none. Can be Low, Medium, High, or Urgent

type - string

The type of the backlog item, or null if none. Can be Epic, Feature, Bug, Spike, or Other.

roughEstimate - number

The rough estimate of the backlog item, or -1 if none. Must be -1 when creating an epic.

roughEstimateUnit - string

The unit of the rough estimate, or null if none. Can be Points, Days, or Hours. The unit must be specified if a rough estimate is specified, and must be the same unit as the project uses for rough estimates.

estimate - number

The estimate of the backlog item, or -1 if none. Must be -1 when creating an epic.

estimateUnit - string

The unit of the estimate, or null if none. Can be Points, Days, or Hours. The unit must be specified if an estimate is specified, and must be the same unit as the project uses for detailed estimates.

index - integer

The index to add the backlog item at, or -1 to add the backlog item at the end. If adding the backlog item inside an epic, this is the index among the existing child backlog items of that epic, else it is the index among the backlog items in the backlog list. Note: This is the index among all backlog items in the epic / backlog list, including backlog items with status Sprint completed and Released.

Result

The id of the new backlog item, as a string.

Example

curl https://api.scrumwise.com/service/api/v1/addBacklogItem -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=BI22354562
  -d projectID=729-11230-1
  -d parentEpicID=729-8943-443
  -d backlogListID=729-44093-5
  -d "name=Example backlog item 1"
  -d "description=An example description."
  -d "link=http://www.example.com"
  -d priority=High
  -d type=Feature
  -d roughEstimate=12.5
  -d roughEstimateUnit=Points
  -d estimate=9.5
  -d estimateUnit=Days
  -d index=3
{
  "objectType" : "Result",
  "dataVersion" : 50802,
  "result" : "729-0-69320"
}

deleteBacklogItem

Deletes a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

Requirements

The backlog item is not allowed to be an epic (to protect against accidental deletions of large epics).

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/deleteBacklogItem -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69320
{
  "objectType" : "Result",
  "dataVersion" : 50803,
  "result" : null
}

assignBacklogItemToKanbanBoard

Assigns a backlog item to a Kanban board.

Parameters

backlogItemID - string

The id of the backlog item.

boardID - string

The id of the Kanban board to assign the backlog item to.

index - integer

The index to place the backlog item at in the list of not archived backlog items assigned to the board, or -1 to place the backlog item at the end of the list.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/assignBacklogItemToKanbanBoard
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d boardID=729-542-4893
  -d index=2
{
  "objectType" : "Result",
  "dataVersion" : 51322,
  "result" : null
}

assignBacklogItemToRelease

Assigns a backlog item to a release.

Parameters

backlogItemID - string

The id of the backlog item.

releaseID - string

The id of the release to assign the backlog item to.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/assignBacklogItemToRelease
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d releaseID=729-632-8542
{
  "objectType" : "Result",
  "dataVersion" : 50709,
  "result" : null
}

assignBacklogItemToSprint

Assigns a backlog item to a sprint.

Parameters

backlogItemID - string

The id of the backlog item.

sprintID - string

The id of the sprint to assign the backlog item to.

teamID - string

The id of the team to assign the backlog item to in the sprint.

index - integer

The index to place the backlog item at in the list of backlog items assigned to the sprint and team, or -1 to place the backlog item at the end of the list.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/assignBacklogItemToSprint
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d sprintID=729-643-5443
  -d teamID=729-331-8482
  -d index=2
{
  "objectType" : "Result",
  "dataVersion" : 50392,
  "result" : null
}

moveBacklogItemToBacklogList

Moves a backlog item to another backlog list.

Parameters

backlogItemID - string

The id of the backlog item.

backlogListID - string

The id of the backlog list that the backlog item should be moved to.

index - integer

The index to place the backlog item at in the target backlog list, or -1 to place the backlog item at the end of the target backlog list. Note: This is the index among all backlog items in the backlog list, including backlog items with status Sprint completed and Released.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/moveBacklogItemToBacklogList
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d backlogListID=729-4543-3632
  -d index=10
{
  "objectType" : "Result",
  "dataVersion" : 50634,
  "result" : null
}

moveBacklogItemToBoardColumn

Moves a backlog item to another board column.

Parameters

backlogItemID - string

The id of the backlog item.

boardColumnID - string

The id of the board column that the backlog item should be moved to.

assignedPersonID - integer

The id of the person that the backlog item should be assigned to, or null if not specified.

Requirements

The backlog item must already be assigned to the board that contains the board column.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/moveBacklogItemToBoardColumn
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d boardColumnID=729-4543-7432
  -d assignedPersonID=729-4531-43372
{
  "objectType" : "Result",
  "dataVersion" : 50632,
  "result" : null
}

setBacklogItemAssignedPersonID

Sets the person that a backlog item is assigned to.

Parameters

backlogItemID - string

The id of the backlog item.

assignedPersonID - string

The id of the person that the backlog item should be assigned to, or null if none.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/setBacklogItemAssignedPersonID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d assignedPersonID=729-4543-3632
{
  "objectType" : "Result",
  "dataVersion" : 50234,
  "result" : null
}

setBacklogItemColor

Sets the color of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

color - string

The new color of the backlog item, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemColor
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d color=Orange
{
  "objectType" : "Result",
  "dataVersion" : 52315,
  "result" : null
}

setBacklogItemCreatorID

Sets the person that created a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

creatorID - string

The new id of the person that created the backlog item, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemCreatorID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d creatorID=729-4543-3632
{
  "objectType" : "Result",
  "dataVersion" : 50807,
  "result" : null
}

setBacklogItemDescription

Sets the description of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

description - string

The new description of the backlog item, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemDescription
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d "description=An example description."
{
  "objectType" : "Result",
  "dataVersion" : 50817,
  "result" : null
}

setBacklogItemEstimate

Sets the estimate of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

estimate - number

The new estimate of the backlog item, or -1 if none.

estimateUnit - string

The unit of the estimate, or null if none. Can be Points, Days, or Hours. The unit must be specified if an estimate is specified, and must be the same unit as the project uses for detailed estimates.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemEstimate
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d estimate=4.5
  -d estimateUnit=Days
{
  "objectType" : "Result",
  "dataVersion" : 50964,
  "result" : null
}

setBacklogItemExternalID

Sets the external id of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

externalID - string

The new external id of the backlog item, or null if none. Must be unique among all backlog items in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-11235-42
  -d externalID=BI25395043
{
  "objectType" : "Result",
  "dataVersion" : 50793,
  "result" : null
}

setBacklogItemLink

Sets the link URL of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

link - string

The new link URL of the backlog item, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemLink -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d "link=http://www.example.com"
{
  "objectType" : "Result",
  "dataVersion" : 50827,
  "result" : null
}

setBacklogItemName

Sets the name of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

name - string

The new name of the backlog item.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemName -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d "name=Example backlog item 1"
{
  "objectType" : "Result",
  "dataVersion" : 50864,
  "result" : null
}

setBacklogItemPositionInKanbanBoard

Sets the position of a not archived backlog item in a Kanban board.

Parameters

backlogItemID - string

The id of the backlog item.

boardID - string

The id of the Kanban board that the backlog item is assigned to.

index - integer

The index to place the backlog item at in the list of not archived backlog items assigned to the board, or -1 to place the backlog item at the end of the list.

Requirements

The backlog item is not archived in the board.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/setBacklogItemPositionInKanbanBoard
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d boardID=729-542-4893
  -d index=2
{
  "objectType" : "Result",
  "dataVersion" : 52322,
  "result" : null
}

setBacklogItemPositionInSprint

Sets the position of a backlog item in a sprint.

Parameters

backlogItemID - string

The id of the backlog item.

sprintID - string

The id of the sprint that the backlog item is assigned to.

teamID - string

The id of the team that the backlog item is assigned to in the sprint.

index - integer

The index to place the backlog item at in the list of backlog items assigned to the team in the sprint, or -1 to place the backlog item at the end of the list.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/setBacklogItemPositionInSprint
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d sprintID=729-542-3223
  -d teamID=729-542-9042
  -d index=2
{
  "objectType" : "Result",
  "dataVersion" : 54975,
  "result" : null
}

setBacklogItemPriority

Sets the priority of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

priority - string

The new priority of the backlog item, or null if none. Can be Low, Medium, High, or Urgent.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemPriority
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d priority=High
{
  "objectType" : "Result",
  "dataVersion" : 50815,
  "result" : null
}

setBacklogItemRemainingWork

Sets the remaining work on a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

remainingWork - number

The new remaining work on the backlog item.

remainingWorkUnit - string

The unit of the remaining work. Can be Points, Days, or Hours. Must be the same unit as the project uses for detailed estimates.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemRemainingWork
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d remainingWork=2.5
  -d remainingWorkUnit=Days
{
  "objectType" : "Result",
  "dataVersion" : 50975,
  "result" : null
}

setBacklogItemReproducible

Sets the reproducible of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

reproducible - string

The new reproducible of the backlog item, or null if none. Can be No, Sometimes, or Always.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemReproducible
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-80332
  -d reproducible=Sometimes
{
  "objectType" : "Result",
  "dataVersion" : 57328,
  "result" : null
}

setBacklogItemResolution

Sets the resolution of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

resolution - string

The new resolution of the backlog item, or null if none. Can be Not enough information, Cannot reproduce, Not a bug, Duplicate, Postponed, Won't fix, or Fixed.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemResolution
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-38493
  -d resolution=Duplicate
{
  "objectType" : "Result",
  "dataVersion" : 55498,
  "result" : null
}

setBacklogItemRoughEstimate

Sets the rough estimate of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

roughEstimate - number

The new rough estimate of the backlog item, or -1 if none.

roughEstimateUnit - string

The unit of the rough estimate, or null if none. Can be Points, Days, or Hours. The unit must be specified if a rough estimate is specified, and must be the same unit as the project uses for rough estimates.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemRoughEstimate
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d roughEstimate=10.25
  -d roughEstimateUnit=Points
{
  "objectType" : "Result",
  "dataVersion" : 50812,
  "result" : null
}

setBacklogItemType

Sets the type of a backlog item.

Parameters

backlogItemID - string

The id of the backlog item.

type - string

The new type of the backlog item, or null if none. Can be Epic, Feature, Bug, Spike, or Other.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogItemType -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d type=Feature
{
  "objectType" : "Result",
  "dataVersion" : 50827,
  "result" : null
}

unassignBacklogItemFromKanbanBoard

Unassigns a backlog item from a Kanban board.

Parameters

backlogItemID - string

The id of the backlog item.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/unassignBacklogItemFromKanbanBoard
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
{
  "objectType" : "Result",
  "dataVersion" : 51642,
  "result" : null
}

unassignBacklogItemFromRelease

Unassigns a backlog item from a release.

Parameters

backlogItemID - string

The id of the backlog item.

releaseID - string

The id of the release that the backlog item should be unassigned from.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/unassignBacklogItemFromRelease
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d releaseID=729-45473-533
{
  "objectType" : "Result",
  "dataVersion" : 51642,
  "result" : null
}

unassignBacklogItemFromSprint

Unassigns a backlog item from a sprint.

Parameters

backlogItemID - string

The id of the backlog item.

sprintID - string

The id of the sprint that the backlog item should be unassigned from.

teamID - string

The id of the team that the backlog item should be unassigned from in the sprint.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/unassignBacklogItemFromSprint
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogItemID=729-0-69327
  -d sprintID=729-45473-533
  -d teamID=729-64821-433
{
  "objectType" : "Result",
  "dataVersion" : 51653,
  "result" : null
}

Backlog list methods

setBacklogListExternalID

Sets the external id of a backlog list.

Parameters

backlogListID - string

The id of the backlog list.

externalID - string

The new external id of the backlog list, or null if none. Must be unique among all backlog lists in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBacklogListExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d backlogListID=729-53083-896
  -d externalID=BL43983
{
  "objectType" : "Result",
  "dataVersion" : 55983,
  "result" : null
}

Board methods

setBoardExternalID

Sets the external id of a board.

Parameters

boardID - string

The id of the board.

externalID - string

The new external id of the board, or null if none. Must be unique among all boards in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBoardExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d boardID=729-22343-233
  -d externalID=BO23908
{
  "objectType" : "Result",
  "dataVersion" : 51436,
  "result" : null
}

Board column methods

setBoardColumnExternalID

Sets the external id of a board column.

Parameters

boardColumnID - string

The id of the board column.

externalID - string

The new external id of the board column, or null if none. Must be unique among all board columns in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setBoardColumnExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d boardColumnID=729-32978-775
  -d externalID=BC398342
{
  "objectType" : "Result",
  "dataVersion" : 52474,
  "result" : null
}

Checklist methods

addChecklist

Adds a checklist.

Parameters

externalID - string

The external id of the checklist, or null if none. Must be unique among all checklists in your account.

ownerObjectType - string

The object type of the object to add the checklist on. Can be Project, Message, Release, Sprint, BacklogItem, Task, Retrospective, or RetrospectiveCard.

ownerObjectID - string

The id of the object to add the checklist on.

name - string

The name of the checklist.

description - string

The description of the checklist, or null if none.

index - integer

The index to add the checklist at in the list of checklists in the owner object, or -1 to add the checklist at the end of the list.

Result

The id of the new checklist, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addChecklist -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=TE5009433
  -d ownerObjectType=BacklogItem
  -d ownerObjectID=729-0-69327
  -d "name=An example checklist"
  -d "description=An example description."
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 51422,
  "result" : "729-0-58932"
}

setChecklistExternalID

Sets the external id of a checklist.

Parameters

checklistID - string

The id of the checklist.

externalID - string

The new external id of the checklist, or null if none. Must be unique among all checklists in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setChecklistExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d checklistID=729-24233-261
  -d externalID=CL63497
{
  "objectType" : "Result",
  "dataVersion" : 56098,
  "result" : null
}

Checklist item methods

addChecklistItem

Adds a checklist item in a checklist.

Parameters

externalID - string

The external id of the checklist item, or null if none. Must be unique among all checklist items in your account.

checklistID - string

The id of the checklist to add the checklist item in.

name - string

The name of the checklist item.

description - string

The description of the checklist item, or null if none.

index - integer

The index to add the checklist item at in the checklist, or -1 to add the checklist item at the end of the checklist.

Result

The id of the new checklist item, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addChecklistItem -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=TE5009433
  -d checklistID=729-0-54098
  -d "name=An example item"
  -d "description=An example description."
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 51432,
  "result" : "729-0-40983"
}

setChecklistItemExternalID

Sets the external id of a checklist item.

Parameters

checklistItemID - string

The id of the checklist item.

externalID - string

The new external id of the checklist item, or null if none. Must be unique among all checklist items in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setChecklistItemExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d checklistItemID=729-53083-896
  -d externalID=CI603942
{
  "objectType" : "Result",
  "dataVersion" : 55983,
  "result" : null
}

setChecklistItemIsChecked

Sets the checked state of a checklist item.

Parameters

checklistItemID - string

The id of the checklist item.

isChecked - string

True if the checklist item should be checked, false if not.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setChecklistItemIsChecked
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d checklistItemID=729-53083-2452
  -d isChecked=true
{
  "objectType" : "Result",
  "dataVersion" : 53229,
  "result" : null
}

Comment methods

addComment

Adds a comment on another object.

Parameters

externalID - string

The external id of the comment, or null if none. Must be unique among all comments in your account.

ownerObjectType - string

The object type of the object to add the comment on. Can be Project, Message, Release, Sprint, BacklogItem, Task, Retrospective, RetrospectiveCard, or File.

ownerObjectID - string

The id of the object to add the comment on.

parentCommentID - string

The id of the parent comment if the new comment is a reply to another comment, or null if the new comment is a top-level comment.

text - string

The text of the comment.

Result

The id of the new comment, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addComment -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=CO43093258
  -d ownerObjectType=BacklogItem
  -d ownerObjectID=729-0-69327
  -d parentCommentID=729-23553-8545
  -d "text=An example comment."
{
  "objectType" : "Result",
  "dataVersion" : 50816,
  "result" : "729-0-89351"
}

deleteComment

Deletes a comment, and all nested replies to the comment.

Parameters

commentID - string

The id of the comment.

Requirements

If the user that the request is made on behalf of is not the creator of the comment, the user must be administrator.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/deleteComment -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d commentID=729-4343-645
{
  "objectType" : "Result",
  "dataVersion" : 50243,
  "result" : null
}

setCommentExternalID

Sets the external id of a comment.

Parameters

commentID - string

The id of the comment.

externalID - string

The new external id of the comment, or null if none. Must be unique among all comments in your account.

Requirements

If the user that the request is made on behalf of is not the creator of the comment, the user must be administrator.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setCommentExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d commentID=729-11753-342
  -d externalID=CO87355644
{
  "objectType" : "Result",
  "dataVersion" : 50797,
  "result" : null
}

setCommentText

Sets the text of a comment.

Parameters

commentID - string

The id of the comment.

text - string

The new text of the comment.

Requirements

If the user that the request is made on behalf of is not the creator of the comment, the user must be administrator.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setCommentText -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d commentID=729-11753-342
  -d "text=A comment text."
{
  "objectType" : "Result",
  "dataVersion" : 50727,
  "result" : null
}

Commit methods

setCommitExternalID

Sets the external id of a commit.

Parameters

commitID - string

The id of the commit.

externalID - string

The new external id of the commit, or null if none. Must be unique among all commits in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setCommitExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d commitID=729-12342-231
  -d externalID=SC34329934
{
  "objectType" : "Result",
  "dataVersion" : 50801,
  "result" : null
}

Custom field methods

setCustomFieldValue

Sets the value of a custom field on an object.

Parameters

customFieldID - string

The id of the custom field.

ownerObjectType - string

The object type of the object whose custom field to set, for example BacklogItem.

ownerObjectID - string

The id of the object whose custom field to set.

value - string

The value to set the custom field to, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setCustomFieldValue -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d customFieldID=729-3082-309
  -d ownerObjectType=BacklogItem
  -d ownerObjectID=729-0-69327
  -d "value=An example value."
{
  "objectType" : "Result",
  "dataVersion" : 58429,
  "result" : null
}

Data methods

getData

Use this method to retrieve data from your account. You can select which data to retrieve using the includeProperties parameter.

Parameters

projectIDs - string

A comma-separated list of the ids of the projects to get, or null to get all projects that are accessible to the user that you are making the request on behalf of.

includeProperties - string

A comma-separated list of optional properties that should be included in the objects in the result, or null to not include any optional properties. A property should be prefixed with the name of the object, for example BacklogItem.comments.

Result

The data, as a Data object.

Example 

curl https://api.scrumwise.com/service/api/v1/getData -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d "projectIDs=729-11230-1,729-31745-129"
  -d "includeProperties=Project.backlogItems,BacklogItem.tasks"
{
  "objectType" : "Result",
  "dataVersion" : 53759,
  "result" : {
    "objectType" : "Data",
    "persons" : null,
    "deletedPersons" : null,
    "projects" : [ {
      "objectType" : "Project",
      "id" : "729-11230-1",
      "externalID" : null,
      "name" : "Project 1",
      "description" : null,
      "link" : null,
      "status" : "Active",
      "roughEstimateUnit" : "Points",
      "detailedEstimateUnit" : "Days",
      "timeTrackingUnit" : "Hours",
      "checklists" : null,
      "comments" : null,
      "attachments" : null,
      "customFields" : null,
      "tags" : null,
      "productOwnerIDs" : [ "729-334-1" ],
      "stakeholderIDs" : [ "729-4151-1", "729-8107-6" ],
      "teams" : null,
      "messages" : null,
      "backlogs:" null,
      "backlogItems" : [ {
        "objectType" : "BacklogItem",
        "id" : "729-11304-21",
        "externalID" : null,
        "itemNumber" : 214,
        "projectID" : "729-11230-1",
        "parentEpicID" : null,
        "backlogListID" : "729-15220-532",
        "name" : "Backlog item 1",
        "description" : null,
        "link" : null,
        "priority" : null,
        "type" : "Feature",
        "color" : "Blue",
        "creatorID" : "729-3232-322",
        "creationDate" : 1547836680000,
        "bugState" : null,
        "reproducible" : null,
        "resolution" : null,
        "releaseID" : null,
        "status" : "New",
        "toDoDate" : null,
        "inProgressDate" : null,
        "toTestDate" : null,
        "doneDate" : null,
        "roughEstimate" : -1.0,
        "estimate" : -1.0,
        "usedTime" : -1.0,
        "remainingWork" : -1.0,
        "sprintID" : null,
        "teamID" : null,
        "boardID" : null,
        "boardColumnID" : null,
        "isArchivedInBoard" : false,
        "assignedPersonIDs" : [ ],
        "dueDate" : null,
        "customFieldValues" : null,
        "tagIDs" : [ ],
        "checklists" : null,
        "comments" : null,
        "attachments" : null,
        "timeEntries" : null,
        "commits" : null,
        "tasks" : [ {
          "objectType" : "Task",
          "id" : "729-11304-28",
          "externalID" : null,
          "taskNumber" : 532,
          "projectID" : "729-11230-1",
          "backlogItemID" : "729-11304-21",
          "name" : "Task 1",
          "description" : null,
          "link" : null,
          "color" : "Blue",
          "creationDate" : 1547836680000,
          "status" : "To do",
          "toDoDate" : 1547836680000,
          "inProgressDate" : null,
          "toTestDate" : null,
          "doneDate" : null,
          "boardColumnID" : null,
          "estimate" : -1.0,
          "usedTime" : -1.0,
          "remainingWork" : -1.0,
          "assignedPersonIDs" : [ ],
          "dueDate" : null,
          "customFieldValues" : null,
          "tagIDs" : [ ],
          "checklists" : null,
          "comments" : null,
          "attachments" : null,
          "timeEntries" : null,
          "commits" : null
        }, ... ],
        "childBacklogItems" : [ ]
      }, ... ],
      "releases" : null,
      "sprints" : null,
      "boards" : null,
      "retrospectives" : null,
      "files" : null,
      "relationships" : null                        
    }, {
      "objectType" : "Project",
      "id" : "729-31745-129",
      "externalID" : null,
      "name" : "Project 2",
      "description" : null,
      ...
    } ]
  }
}

getDataVersion

Returns the current data version of the data in your account. Use this method to poll for changes in your data.

Parameters

(None)

Result

The current data version, as an integer.

Example 

curl https://api.scrumwise.com/service/api/v1/getDataVersion -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
{
  "objectType" : "Result",
  "dataVersion" : 50785,
  "result" : 50785
}

File methods

getFileContents

Returns the contents of a file.

Parameters

fileID - string

The id of the file.

Result

The file contents, encoded in Base64 format.

Example

curl https://api.scrumwise.com/service/api/v1/getFileContents
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d fileID=729-5367-231
{
  "objectType" : "Result",
  "dataVersion" : 53475,
  "result" : "QmFzZTY0IGlzIGEgZ3JvdXAgb2Ygc2ltaWxhciBiaW5hcnktd..."
}

setFileExternalID

Sets the external id of a file.

Parameters

fileID - string

The id of the file.

externalID - string

The new external id of the file, or null if none. Must be unique among all files in your account.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/setFileExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d fileID=729-43382-783
  -d externalID=FIL490809
{
  "objectType" : "Result",
  "dataVersion" : 50792,
  "result" : null
}

Message methods

addMessage

Adds a new message.

Parameters

externalID - string

The external id of the message, or null if none. Must be unique among all messages in your account.

projectID - string

The id of the project to add the message in.

title - string

The title of the message.

text - string

The text of the message, or null if none.

link - string

The link URL of the message, or null if none.

type - string

The type of the message, or null if none. Can be Announcement, Information, Question, Idea, To do, or Other.

color - string

The color of the message, or null for the default color. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

Result

The id of the new message, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addMessage -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=MSG309636
  -d projectID=729-420-48903
  -d "title=Example message 1"
  -d "text=An example text."
  -d "link=http://www.example.com"
  -d type=Announcement
  -d color=Red
{
  "objectType" : "Result",
  "dataVersion" : 59632,
  "result" : "729-363-90822"
}

setMessageExternalID

Sets the external id of a message.

Parameters

messageID - string

The id of the message.

externalID - string

The new external id of the message, or null if none. Must be unique among all messages in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setMessageExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d messageID=729-5325-542
  -d externalID=MSG93822
{
  "objectType" : "Result",
  "dataVersion" : 55423,
  "result" : null
}

Person methods

addPerson

Adds a person.

Parameters

externalID - string

The external id of the person, or null if none. Must be unique among all persons in your account.

firstName - string

The first name of the person.

lastName - string

The last name of the person, or null if none.

nickname - string

The nickname of the person, or null if none.

emailAddress - string

The email address of the person.

description - string

The description of the person, or null if none.

groupName - string

The name of the group to add the person to, or null if none.

Result

The id of the new person, as a string.

Requirements

The user that the request is made on behalf of must be administrator.

Example 

curl https://api.scrumwise.com/service/api/v1/addPerson -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=PE3093860
  -d firstName=Edward
  -d lastName=Johnson
  -d nickname=Ed
  -d emailAddress=ed@example.com
  -d "description=An example description."
  -d "groupName=Example group"
{
  "objectType" : "Result",
  "dataVersion" : 50239,
  "result" : "729-0-59592"
}

setPersonExternalID

Sets the external id of a person.

Parameters

personID - string

The id of the person.

externalID - string

The new external id of the person, or null if none. Must be unique among all persons in your account.

Result

null

Requirements

If the user that the request is made on behalf of is not the same as the person whose external id is to be set, the user must be administrator.

Example 

curl https://api.scrumwise.com/service/api/v1/setPersonExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d personID=729-11304-39
  -d externalID=PE39872462
{
  "objectType" : "Result",
  "dataVersion" : 50802,
  "result" : null
}

Project methods

addProject

Adds a new project.

Parameters

externalID - string

The external id of the project, or null if none. Must be unique among all projects in your account.

name - string

The name of the project. Must be unique among all projects in your account.

description - string

The description of the project, or null if none.

link - string

The link URL of the project, or null if none.

roughEstimateUnit - string

The unit to use for rough estimates in the project, or null for the default. Can be Points, Days, or Hours.

detailedEstimateUnit - string

The unit to use for detailed estimates in the project, or null for the default. Can be Points, Days, or Hours.

timeTrackingUnit - string

The unit to use for detailed time tracking in the project, or null for the default. Can be Points, Days, or Hours.

index - integer

The index to add the project at in the list of all projects in your account, or -1 to add the project at the end of the list. Note: This is the index among all projects in your account, including projects with status Archived.

Requirements

If access control on projects is turned on in your account, the user that the request is made on behalf of must be administrator.

Result

The id of the new project, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addProject -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=PR43268328
  -d "name=Project 1"
  -d "description=An example project."
  -d "link=http://www.example.com"
  -d roughEstimateUnit=Points
  -d detailedEstimateUnit=Days
  -d timeTrackingUnit=Hours
  -d index=5
{
  "objectType" : "Result",
  "dataVersion" : 50818,
  "result" : "729-0-69354"
}

setProjectExternalID

Sets the external id of a project.

Parameters

projectID - string

The id of the project.

externalID - string

The new external id of the project, or null if none. Must be unique among all projects in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setProjectExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d projectID=729-11324-623
  -d externalID=PR58976373
{
  "objectType" : "Result",
  "dataVersion" : 50803,
  "result" : null
}

Relationship methods

addRelationship

Adds a relationship between to objects.

Parameters

externalID - string

The external id of the relationship, or null if none. Must be unique among all relationships in your account.

type - string

The type of the relationship. Can be Must be done after, Must be done before, Is dependent on, Is dependency for, Is blocked by, Is blocking, Is bug on, Has bug, Is duplicate of, Has duplicate, or Is related to.

fromObjectType - string

The object type of the object that the relationship should start at. Can be Release, Sprint, BacklogItem, Task, Retrospective, or RetrospectiveCard.

fromObjectType - string

The id of the object that the relationship should start at.

toObjectType - string

The object type of the object that the relationship should end at. Can be Release, Sprint, BacklogItem, or Task.

toObjectType - string

The id of the object that the relationship should end at.

description - string

The description of the relationship, or null if none.

Result

The id of the new relationship, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addRelationship -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=REL408337
  -d "type=Is dependent on"
  -d fromObjectType=BacklogItem
  -d fromObjectID=729-0-69327
  -d toObjectType=BacklogItem
  -d toObjectID=729-3220-5409
  -d "description=An example relationship."
{
  "objectType" : "Result",
  "dataVersion" : 55094,
  "result" : "729-0-29321"
}

deleteRelationship

Deletes a relationship.

Parameters

relationshipID - string

The id of the relationship.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/deleteRelationship -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d relationshipID=729-737-7385
{
  "objectType" : "Result",
  "dataVersion" : 51547,
  "result" : null
}

setRelationshipExternalID

Sets the external id of a relationship.

Parameters

relationshipID - string

The id of the relationship.

externalID - string

The new external id of the relationship, or null if none. Must be unique among all relationships in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setRelationshipExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d relationshipID=729-11753-342
  -d externalID=REL636944
{
  "objectType" : "Result",
  "dataVersion" : 56943,
  "result" : null
}

Release methods

addRelease

Adds a new release.

Parameters

externalID - string

The external id of the release, or null if none. Must be unique among all releases in your account.

projectID - string

The id of the project to add the release in.

name - string

The name of the release. Must be unique among all releases in the project.

description - string

The description of the release, or null if none.

link - string

The link URL of the release, or null if none.

startDate - string

The start date of the release, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

releaseDate - string

The release date of the release, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

bestCaseVelocityPerWeek - number

The best-case velocity per week of the release, in the unit used for rough estimates in the project, or -1 if none.

expectedVelocityPerWeek - number

The expected velocity per week of the release, in the unit used for rough estimates in the project, or -1 if none.

worstCaseVelocityPerWeek - number

The worst-case velocity per week of the release, in the unit used for rough estimates in the project, or -1 if none.

velocityUnit - string

The unit of the velocities per week, or null if none. Can be Points, Days, or Hours. The unit must be specified if a velocity per week is specified, and must be the same unit as the project uses for rough estimates.

index - integer

The index to add the release at in the list of releases in the project, or -1 to add the release at the end of the list.

Result

The id of the new release, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addRelease -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=R54093
  -d projectID=729-420-48903
  -d "name=Example release 1"
  -d "description=An example description."
  -d "link=http://www.example.com"
  -d startDate=2019-05-10
  -d releaseDate=2019-08-20
  -d bestCaseVelocityPerWeek=20
  -d expectedVelocityPerWeek=15
  -d worstCaseVelocityPerWeek=10
  -d velocityUnit=Points
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 59544,
  "result" : "729-304-43931"
}

deleteRelease

Deletes a release.

Parameters

releaseID - string

The id of the release.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/deleteRelease -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d releaseID=729-3732-843
{
  "objectType" : "Result",
  "dataVersion" : 54332,
  "result" : null
}

setReleaseDates

Sets the start date and the release date of a release.

Parameters

releaseID - string

The id of the release.

startDate - string

The start date of the release, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

releaseDate - string

The release date of the release, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setReleaseDates -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d releaseID=729-45473-533
  -d startDate=2019-05-10
  -d releaseDate=2019-08-20
{
  "objectType" : "Result",
  "dataVersion" : 50432,
  "result" : null
}

setReleaseDescription

Sets the description of a release.

Parameters

releaseID - string

The id of the release.

description - string

The new description of the release, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setReleaseDescription -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d releaseID=729-45473-533
  -d "description=An example description."
{
  "objectType" : "Result",
  "dataVersion" : 50432,
  "result" : null
}

setReleaseExternalID

Sets the external id of a release.

Parameters

releaseID - string

The id of the release.

externalID - string

The new external id of the release, or null if none. Must be unique among all releases in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setReleaseExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d releaseID=729-15367-3125
  -d externalID=RE86536527
{
  "objectType" : "Result",
  "dataVersion" : 50842,
  "result" : null
}

setReleaseName

Sets the name of a release.

Parameters

releaseID - string

The id of the release.

name - string

The new name of the release. Must be unique among all releases in the project.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setReleaseName -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d releaseID=729-11643-433
  -d "name=Example release 1"
{
  "objectType" : "Result",
  "dataVersion" : 52355,
  "result" : null
}

Retrospective methods

setRetrospectiveExternalID

Sets the external id of a retrospective.

Parameters

retrospectiveID - string

The id of the retrospective.

externalID - string

The new external id of the retrospective, or null if none. Must be unique among all retrospectives in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setRetrospectiveExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d retrospectiveID=729-4332-322
  -d externalID=RETRO93822
{
  "objectType" : "Result",
  "dataVersion" : 53422,
  "result" : null
}

Retrospective card methods

setRetrospectiveCardExternalID

Sets the external id of a retrospective card.

Parameters

retrospectiveCardID - string

The id of the card.

externalID - string

The new external id of the card, or null if none. Must be unique among all retrospective cards in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setRetrospectiveCardExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d retrospectiveCardID=729-2233-2225
  -d externalID=RCARD32332
{
  "objectType" : "Result",
  "dataVersion" : 56433,
  "result" : null
}

Sprint methods

addSprint

Adds a new sprint.

Parameters

externalID - string

The external id of the sprint, or null if none. Must be unique among all sprints in your account.

projectID - string

The id of the project to add the sprint in.

name - string

The name of the sprint. Must be unique among all sprints in the project.

description - string

The description of the sprint, or null if none.

link - string

The link URL of the sprint, or null if none.

startDate - string

The start date of the sprint, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

endDate - string

The end date of the sprint, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

boardID - string

The id of the board that the sprint should use, or null if none.

index - integer

The index to add the sprint at in the list of sprints in the project, or -1 to add the sprint at the end of the list.

Result

The id of the new sprint, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addSprint -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=SP498034
  -d projectID=729-420-48903
  -d "name=Example sprint 1"
  -d "description=An example description."
  -d "link=http://www.example.com"
  -d startDate=2019-05-10
  -d endDate=2019-05-23
  -d boardID=729-424-3292
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 59388,
  "result" : "729-30-49832"
}

deleteSprint

Deletes a sprint.

Parameters

sprintID - string

The id of the sprint.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/deleteSprint -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d sprintID=729-37332-1843
{
  "objectType" : "Result",
  "dataVersion" : 54327,
  "result" : null
}

setAvailableTimeForTeamInSprint

Sets the available time for a team in a sprint.

Parameters

sprintID - string

The id of the sprint.

teamID - string

The id of the team.

availableTime - number

The new available time for the team, or -1 if the available time should not be specified for the team.

availableTimeUnit - string

The unit of the available time, or null if none. Can be Points, Days, or Hours. The unit must be specified if an available time is specified, and must be the same unit as the project uses for detailed estimates.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setAvailableTimeForTeamInSprint
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d sprintID=729-48373-432
  -d teamID=729-6432-392
  -d availableTime=40
  -d availableTimeUnit=Days
{
  "objectType" : "Result",
  "dataVersion" : 51049,
  "result" : null
}

setSprintDates

Sets the start and end dates of a sprint.

Parameters

sprintID - string

The id of the sprint.

startDate - string

The start date of the sprint, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

endDate - string

The end date of the sprint, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setSprintDates -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d sprintID=729-48373-432
  -d startDate=2019-05-06
  -d endDate=2019-05-19
{
  "objectType" : "Result",
  "dataVersion" : 56436,
  "result" : null
}

setSprintDescription

Sets the description of a sprint.

Parameters

sprintID - string

The id of the sprint.

description - string

The new description of the sprint, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setSprintDescription -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d sprintID=729-48373-432
  -d "description=An example description."
{
  "objectType" : "Result",
  "dataVersion" : 54638,
  "result" : null
}

setSprintExternalID

Sets the external id of a sprint.

Parameters

sprintID - string

The id of the sprint.

externalID - string

The new external id of the sprint, or null if none. Must be unique among all sprints in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setSprintExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d sprintID=729-10367-745
  -d externalID=SP86486527
{
  "objectType" : "Result",
  "dataVersion" : 50810,
  "result" : null
}

setSprintName

Sets the name of a sprint.

Parameters

sprintID - string

The id of the sprint.

name - string

The new name of the sprint. Must be unique among all sprints in the project.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setSprintName -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d sprintID=729-10367-745
  -d "name=Example sprint 1"
{
  "objectType" : "Result",
  "dataVersion" : 52309,
  "result" : null
}

Tag methods

addTag

Adds a new tag. Use this method to create a new tag, and then use the addTagOnObject method to add the tag on specific objects.

Parameters

externalID - string

The external id of the tag, or null if none. Must be unique among all tags in your account.

projectID - string

The id of the project to add the tag in.

name - string

The name of the tag. Must be unique among all tags in the project.

description - string

The description of the tag, or null if none.

color - string

The color of the tag, or null for the default color. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

index - integer

The index to add the tag at in the list of all tags in the project, or -1 to add the tag at the end of the list.

Result

The id of the new tag, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addTag -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=TG49303752
  -d projectID=729-11230-1
  -d "name=Tag 1"
  -d "description=An example tag."
  -d color=Red
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 50821,
  "result" : "729-0-69363"
}

deleteTag

Deletes a tag.

Parameters

tagID - string

The id of the tag.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/deleteTag -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d tagID=729-26431-545
{
  "objectType" : "Result",
  "dataVersion" : 48543,
  "result" : null
}

setTagExternalID

Sets the external id of a tag.

Parameters

tagID - string

The id of the tag.

externalID - string

The new external id of the tag, or null if none. Must be unique among all tags in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTagExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d tagID=729-14308-3532
  -d externalID=TG34034090
{
  "objectType" : "Result",
  "dataVersion" : 50810,
  "result" : null
}

addTagOnObject

Adds a tag on an object.

Parameters

tagID - string

The id of the tag to add on the object.

objectType - string

The object type of the object to add the tag on. Can be Message, Release, Sprint, BacklogItem, Task, Retrospective, RetrospectiveCard, or File.

objectID - string

The id of the object to add the tag on.

Requirements

The object does not already have the tag.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/addTagOnObject -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d tagID=729-0-69363
  -d objectType=BacklogItem
  -d objectID=729-43532-632
{
  "objectType" : "Result",
  "dataVersion" : 50822,
  "result" : null
}

removeTagFromObject

Removes a tag from an object.

Parameters

tagID - string

The id of the tag to remove from the object.

objectType - string

The object type of the object to remove the tag from. Can be Message, Release, Sprint, BacklogItem, Task, Retrospective, RetrospectiveCard, or File.

objectID - string

The id of the object to remove the tag from.

Requirements

The object must have the tag.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/removeTagFromObject -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d tagID=729-0-69363
  -d objectType=BacklogItem
  -d objectID=729-43532-632
{
  "objectType" : "Result",
  "dataVersion" : 50823,
  "result" : null
}

Task methods

addTask

Adds a task in a backlog item.

Parameters

externalID - string

The external id of the task, or null if none. Must be unique among all tasks in your account.

backlogItemID - string

The id of the backlog item to add the task in.

name - string

The name of the task.

description - string

The description of the task, or null if none.

link - string

The link URL of the task, or null if none.

estimate - number

The estimate of the task, or -1 if none.

estimateUnit - string

The unit of the estimate, or null if none. Can be Points, Days, or Hours. The unit must be specified if an estimate is specified, and must be the same unit as the project uses for detailed estimates.

index - integer

The index to add the task at in the list of tasks in the backlog item, or -1 to add the task at the end of the list.

Result

The id of the new task, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addTask -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=TA50984352
  -d backlogItemID=729-0-69327
  -d "name=Example task 1"
  -d "description=An example description."
  -d "link=http://www.example.com"
  -d estimate=9.5
  -d estimateUnit=Days
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 50827,
  "result" : "729-0-73782"
}

deleteTask

Deletes a task.

Parameters

taskID - string

The id of the task.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/deleteTask -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-37563-549
{
  "objectType" : "Result",
  "dataVersion" : 54989,
  "result" : null
}

moveTaskToBoardColumn

Moves a task to another board column.

Parameters

taskID - string

The id of the task.

boardColumnID - string

The id of the board column that the task should be moved to.

assignedPersonID - integer

The id of the person that the task should be assigned to, or null if not specified.

Requirements

The task must already be assigned to the board that contains the board column.

Result

null

Example

curl https://api.scrumwise.com/service/api/v1/moveTaskToBoardColumn
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-0-62214
  -d boardColumnID=729-4543-7432
  -d assignedPersonID=729-4531-43372
{
  "objectType" : "Result",
  "dataVersion" : 50632,
  "result" : null
}

setTaskAssignedPersonID

Sets the person that a task is assigned to.

Parameters

taskID - string

The id of the task.

assignedPersonID - string

The id of the person that the task should be assigned to, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskAssignedPersonID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-15443-202
  -d assignedPersonID=729-4543-3632
{
  "objectType" : "Result",
  "dataVersion" : 50164,
  "result" : null
}

setTaskColor

Sets the color of a task.

Parameters

taskID - string

The id of the task.

color - string

The new color of the task, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskColor -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-11254-642
  -d color=Orange
{
  "objectType" : "Result",
  "dataVersion" : 51352,
  "result" : null
}

setTaskDescription

Sets the description of a task.

Parameters

taskID - string

The id of the task.

description - string

The new description of the task, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskDescription -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-15443-202
  -d "description=An example description."
{
  "objectType" : "Result",
  "dataVersion" : 50232,
  "result" : null
}

setTaskEstimate

Sets the estimate of a task.

Parameters

taskID - string

The id of the task.

estimate - number

The new estimate of the task, or -1 if none.

estimateUnit - string

The unit of the estimate, or null if none. Can be Points, Days, or Hours. The unit must be specified if an estimate is specified, and must be the same unit as the project uses for detailed estimates.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskEstimate
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-0-48932
  -d estimate=1.5
  -d estimateUnit=Days
{
  "objectType" : "Result",
  "dataVersion" : 51463,
  "result" : null
}

setTaskExternalID

Sets the external id of a task.

Parameters

taskID - string

The id of the task.

externalID - string

The new external id of the task, or null if none. Must be unique among all tasks in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-11254-642
  -d externalID=TA93863984
{
  "objectType" : "Result",
  "dataVersion" : 50811,
  "result" : null
}

setTaskLink

Sets the link URL of a task.

Parameters

taskID - string

The id of the task.

link - string

The new link URL of the task, or null if none.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskLink -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-11254-642
  -d "link=http://www.example.com"
{
  "objectType" : "Result",
  "dataVersion" : 50923,
  "result" : null
}

setTaskName

Sets the name of a task.

Parameters

taskID - string

The id of the task.

name - string

The new name of the task.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskName -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-11254-642
  -d "name=Example task 1"
{
  "objectType" : "Result",
  "dataVersion" : 50925,
  "result" : null
}

setTaskRemainingWork

Sets the remaining work on a task.

Parameters

taskID - string

The id of the task.

remainingWork - number

The new remaining work on the task.

remainingWorkUnit - string

The unit of the remaining work. Can be Points, Days, or Hours. Must be the same unit as the project uses for detailed estimates.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTaskRemainingWork
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d taskID=729-0-57883
  -d remainingWork=1.5
  -d remainingWorkUnit=Days
{
  "objectType" : "Result",
  "dataVersion" : 51321,
  "result" : null
}

Team methods

setTeamExternalID

Sets the external id of a team.

Parameters

teamID - string

The id of the team.

externalID - string

The new external id of the team, or null if none. Must be unique among all teams in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTeamExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d teamID=729-12445-3324
  -d externalID=TE43903908
{
  "objectType" : "Result",
  "dataVersion" : 50820,
  "result" : null
}

Time entry methods

addTimeEntry

Adds a time entry.

Parameters

externalID - string

The external id of the time entry, or null if none. Must be unique among all time entries in your account.

ownerObjectType - string

The object type of the object that the time was used on. Can be BacklogItem or Task.

ownerObjectID - string

The id of the object that the time was used on.

date - string

The date on which the time was used, as a string in the format YYYY-MM-DD, for example "2019-10-27".

personID - string

The id of the person that used the time.

description - string

The description of the used time, or null if none.

usedTime - number

The amount of time that was used.

usedTimeUnit - string

The unit of the used time. Can be Points, Days, or Hours. The unit must be the same unit as the project uses for detailed time tracking.

index - integer

The index to add the time entry at in the list of time entries in the owner object, or -1 to add the time entry at the end of the list.

Result

The id of the new time entry, as a string.

Example 

curl https://api.scrumwise.com/service/api/v1/addTimeEntry -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d externalID=TE5009433
  -d ownerObjectType=BacklogItem
  -d ownerObjectID=729-0-69327
  -d date=2019-05-16
  -d personID=729-4543-3632
  -d "description=An example description."
  -d usedTime=1.5
  -d usedTimeUnit=Hours
  -d index=0
{
  "objectType" : "Result",
  "dataVersion" : 51844,
  "result" : "729-0-84432"
}

deleteTimeEntry

Deletes a time entry.

Parameters

timeEntryID - string

The id of the time entry to delete.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/deleteTimeEntry -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d timeEntryID=729-34338-3098
{
  "objectType" : "Result",
  "dataVersion" : 56443,
  "result" : null
}

getTimeEntries

Returns the time entries that match the specified criteria.

Parameters

projectIDs - string

A comma-separated list of the ids of the projects to get time entries from, or null to get time entries from all projects that are accessible to the user that you are making the request on behalf of.

personID - string

The id of the person that used the time, or null to get time entries for all persons.

fromDate - string

The first date to get time entries for, as a string in the format YYYY-MM-DD, for example "2019-05-01", or null if none.

toDate - string

The last date to get time entries for, as a string in the format YYYY-MM-DD, for example "2019-05-31", or null if none.

Result

The time entries, as an array of TimeEntry objects, empty if there are no matching time entries.

Example 

curl https://api.scrumwise.com/service/api/v1/getTimeEntries -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d "projectIDs=729-11230-1,729-31745-129"
  -d personID=729-4543-3632
  -d fromDate=2019-05-01
  -d toDate=2019-05-31
{
  "objectType" : "Result",
  "dataVersion" : 51329,
  "result" : [ {
      "objectType" : "TimeEntry",
      "id" : "729-11305-19",
      "externalID" : null,
      "projectID" : "729-11230-1",
      "ownerObjectType" : "BacklogItem",
      "ownerObjectID" : "729-11304-31",
      "date" : "2019-05-06",
      "personID" : "729-4543-3632",
      "description" : "An example description.",
      "usedTime" : 2.5,
      "customFieldValues" : null
  }, ... ]
}

setTimeEntryExternalID

Sets the external id of a time entry.

Parameters

timeEntryID - string

The id of the time entry.

externalID - string

The new external id of the team, or null if none. Must be unique among all teams in your account.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTimeEntryExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d timeEntryID=729-9304-3924
  -d externalID=TE34980254
{
  "objectType" : "Result",
  "dataVersion" : 50812,
  "result" : null
}

setTimeEntryUsedTime

Sets the used time of a time entry.

Parameters

timeEntryID - string

The id of the time entry.

usedTime - number

The amount of time that was used.

usedTimeUnit - string

The unit of the used time. Can be Points, Days, or Hours. The unit must be the same unit as the project uses for detailed time tracking.

Result

null

Example 

curl https://api.scrumwise.com/service/api/v1/setTimeEntryUsedTime
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d timeEntryID=729-9304-3924
  -d usedTime=1.5
  -d usedTimeUnit=Hours
{
  "objectType" : "Result",
  "dataVersion" : 50393,
  "result" : null
}

Objects

Attachment object

A file attachment on another object.

Properties

objectType - string

The type of the object, always Attachment.

id - string

The id of the attachment.

externalID - string

The external id of the attachment, or null if none. Unique among all attachments in your account.

projectID - string

The id of the project that contains the attachment.

ownerObjectType - string

The object type of the object that the attachment is attached to, for example BacklogItem.

ownerObjectID - string

The id of the object that the attachment is attached to.

name - string

The name of the attachment, or null if none.

description - string

The description of the attachment, or null if none.

fileName - string

The file name of the attachment, or null if none.

thumbnailURL - string

The URL of a preview image of the file, or null if not available.

url - string

The URL of the file.

Example

{
  "objectType" : "Attachment",
  "id" : "729-8641-15",
  "externalID" : null,
  "projectID" : "729-3251-651",
  "ownerObjectType" : "BacklogItem",
  "ownerObjectID" : "729-17823-1322",
  "name" : "Example attachment",
  "description" : "An example description.",
  "fileName" : "Example.png",
  "thumbnailURL" : "https://www.scrumwise.com/service/resource...",
  "url" : "https://www.scrumwise.com/service/resource..."
}

Backlog object

A backlog in a project. The backlog items in a project are organized into backlogs and backlog lists. A project has one or more backlogs, which each contain one or more backlog lists, which in turn each contain zero or more backlog items.

Properties

objectType - string

The type of the object, always Backlog.

id - string

The id of the backlog.

externalID - string

The external id of the backlog, or null if none. Unique among all backlogs in your account.

projectID - string

The id of the project that contains the backlog.

name - string

The name of the backlog.

description - string

The description of the backlog, or null if none.

color - string

The color of the backlog, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

isArchived - boolean

True if the backlog is archived, false if not.

backlogLists - array of BacklogList objects

The backlog lists in the backlog, at least one.

Example 

{
  "objectType" : "Backlog",
  "id" : "729-5931-4348",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "name" : "Example backlog",
  "description" : "An example description.",
  "color" : "Blue",
  "isArchived" : false,
  "backlogLists" : [ {
    "objectType" : "BacklogList",
    "id" : "729-2397-462",
    "externalID" : null,
    "projectID" : "729-1321-1244",
    ...
  }, ... ]
}

BacklogItem object

A backlog item.

Properties

objectType - string

The type of the object, always BacklogItem.

id - string

The id of the backlog item.

externalID - string

The external id of the backlog item, or null if none. Unique among all backlog items in your account.

itemNumber - integer

The item number of the backlog item, starting from 1. Unique among all backlog items in your account.

projectID - string

The id of the project that contains the backlog item.

parentEpicID - string

The id of the parent epic that the backlog item belongs to, or null if none.

backlogListID - string

The id of the backlog list that contains the backlog item.

name - string

The name of the backlog item.

description - string

The description of the backlog item, or null if none.

link - string

The link URL of the backlog item, or null if none.

priority - string

The priority of the backlog item, or null if none. Can be Low, Medium, High, or Urgent.

type - string

The type of the backlog item, or null if none. Can be Epic, Feature, Bug, Spike, or Other.

color - string

The color of the backlog item, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

creatorID - string

The id of the person that created the backlog item, or null if none. This can refer to a Person or DeletedPerson object.

creationDate - integer

The date where the backlog item was created, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if not available.

bugState - string

The bug state of the backlog item, or null if the backlog item is not a bug. Can be Open or Closed.

reproducible - string

The reproducibility of the bug, or null if not specified or if the backlog item is not a bug. Can be No, Sometimes, or Always.

resolution - string

The resolution the backlog item, or null if not specified or if the backlog item is not a bug. Can be Not enough information, Cannot reproduce, Not a bug, Duplicate, Postponed, Won't fix, or Fixed.

releaseID - string

The id of the release that the backlog item is assigned to, or null if the backlog item is not assigned to a release.

status - string

The status of the backlog item. Can be New, Ready for estimation, Ready for sprint, Assigned to sprint, To do, In progress, To test, Done, Sprint completed, or Released.

toDoDate - integer

The date where the backlog item was set to status To do, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the backlog item has not had this status or the date is not available.

inProgressDate - integer

The date where the backlog item was set to status In progress, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the backlog item has not had this status or the date is not available.

toTestDate - integer

The date where the backlog item was set to status To test, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the backlog item has not had this status or the date is not available.

doneDate - integer

The date where the backlog item was set to status Done, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the backlog item has not had this status or the date is not available.

roughEstimate - number

The rough estimate of the backlog item, in the unit used for rough estimates in the project, or -1 if none.

estimate - number

The estimate of the backlog item, in the unit used for detailed estimates in the project, or -1 if none.

usedTime - number

The time used on the backlog item, or -1 if not specified. If detailed time tracking is used, this is in the unit used for detailed time tracking in the project, else the unit used for detailed estimates.

remainingWork - number

The remaining work on the backlog item, in the unit used for detailed estimates in the project, or -1 if not specified.

sprintID - string

The id of the sprint that the backlog item is assigned to, or null if the backlog item is not assigned to a sprint.

teamID - string

The id of the team that the backlog item is assigned to in the sprint, or null if the backlog item is not assigned to a sprint.

boardID - string

The id of the board that the backlog item is assigned to, or null if the backlog item is not assigned to a board.

boardColumnID - string

The id of the board column that the item is in, in the board that it is assigned to, or null if none. If the backlog item has tasks, the backlog item is not itself in a board column, so this property is null. Instead, each task is in a column.

isArchivedInBoard - boolean

True if the backlog item is archived in the board that it is assigned to, false if not.

assignedPersonIDs - array of strings

The ids of the persons that the backlog item is assigned to, empty if none. This can refer to Person or DeletedPerson objects.

dueDate - string

The due date of the backlog item, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

customFieldValues - array of CustomFieldValue objects

The custom field values on the backlog item, empty if none, or null if not included.

tagIDs - array of strings

The ids of the tags on the backlog item, empty if none.

checklists - array of Checklist objects

The checklists on the backlog item, empty if none, or null if not included.

comments - array of Comment objects

The comments on the backlog item, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the backlog item, empty if none, or null if not included.

timeEntries - array of TimeEntry objects

The time entries on the backlog item, empty if none, or null if not included.

commits - array of Commit objects

The commits on the backlog item, empty if none, or null if not included.

tasks - array of Task objects

The tasks in the backlog item, empty if none, or null if not included.

childBacklogItems - array of BacklogItem objects

The child backlog items of the backlog item, empty if none. This includes only the child backlog items that are placed inside the epic. If a child backlog item is placed outside of the epic, it will occur on its own in the backlog, outside of the parent epic.

Example 

{
  "objectType" : "BacklogItem",
  "id" : "729-33220-627",
  "externalID" : null,
  "itemNumber" : 2149,
  "projectID" : "729-11230-132",
  "parentEpicID" : null,
  "backlogListID" : "729-15220-532",
  "name" : "Example backlog item 1",
  "description" : "An example description.",
  "link" : "http://www.example.com",
  "priority" : "High",
  "type" : "Feature",
  "color" : "Blue",
  "creatorID" : "729-32144-2210",
  "creationDate" : 1547836680000,
  "bugState" : null,
  "reproducible" : null,
  "resolution" : null,
  "releaseID" : "729-3490-4392",
  "status" : "In progress",
  "toDoDate" : 1547984280000,
  "inProgressDate" : 1548081480000,
  "toTestDate" : null,
  "doneDate" : null,
  "roughEstimate" : 15.0,
  "estimate" : 21.25,
  "usedTime" : 9.5,
  "remainingWork" : 12.5,
  "sprintID" : "729-5445-4334",
  "teamID" : "729-6764-8437",
  "boardID" : "729-2345-322",
  "boardColumnID" : "729-74532-4342",
  "isArchivedInBoard" : false,
  "assignedPersonIDs" : [ "729-5444-343" ],
  "dueDate" : null,
  "customFieldValues" : null,
  "tagIDs" : [ "729-14820-466", "729-6893-337" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "timeEntries" : null,
  "commits" : null,
  "tasks" : null,
  "childBacklogItems" : [ ]
}

BacklogList object

A backlog list in a backlog. A backlog list contains zero or more backlog items.

Properties

objectType - string

The type of the object, always BacklogList.

id - string

The id of the backlog list.

externalID - string

The external id of the backlog list, or null if none. Unique among all backlog lists in your account.

projectID - string

The id of the project that contains the backlog list.

backlogID - string

The id of the backlog that contains the backlog list.

name - string

The name of the backlog list.

description - string

The description of the backlog list, or null if none.

color - string

The color of the backlog list, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

isArchived - boolean

True if the backlog list is archived, false if not.

backlogItems - array of BacklogItem objects

The backlog items in the backlog list, empty if none.

Example 

{
  "objectType" : "BacklogList",
  "id" : "729-43612-1229",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "backlogID" : "729-5931-3524",
  "name" : "Example backlog list",
  "description" : "An example description.",
  "color" : "Green",
  "isArchived" : true,
  "backlogItems" : [ {
    "objectType" : "BacklogItem",
    "id" : "729-11304-21",
    "externalID" : null,
    "itemNumber" : 214,
    ...
  }, ... ]
}

Board object

A Scrum task board or Kanban board.

Properties

objectType - string

The type of the object, always Board.

id - string

The id of the board.

externalID - string

The external id of the board, or null if none. Unique among all boards in your account.

projectID - string

The id of the project that contains the board.

name - string

The name of the board.

description - string

The description of the board, or null if none.

type - string

The type of the board. Can be Scrum or Kanban.

columns - array of BoardColumn objects

The columns in the board, empty if none.

assignedBacklogItemIDs - array of strings

The ids of the backlog items that are assigned to the board, empty if none.

Example 

{
  "objectType" : "Board",
  "id" : "729-3231-632",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "name" : "Example task board",
  "description" : "An example description.",
  "type" : "Scrum",
  "columns" : [ {
    "objectType" : "BoardColumn",
    "id" : "729-1242-31",
    "externalID" : null,
    "projectID" : "729-1321-1244",
    ...
  }, ... ],
  "assignedBacklogItemIDs" : [ "729-3056-422", "729-4333-633" ]
}

BoardColumn object

A column in a board.

Properties

objectType - string

The type of the object, always BoardColumn.

id - string

The id of the board column.

externalID - string

The external id of the board column, or null if none. Unique among all board columns in your account.

projectID - string

The id of the project that contains the board column.

boardID - string

The id of the board that the board column belongs to.

name - string

The name of the board column.

description - string

The description of the board column, or null if none.

status - string

The status that backlog items and tasks will have when they are in this column. Can be To do, In progress, To test, or Done

Example 

{
  "objectType" : "BoardColumn",
  "id" : "729-39825-564",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "boardID" : "729-3231-632",
  "name" : "Example column",
  "description" : "An example description.",
  "status" : "In progress"
}

Checklist object

A checklist.

Properties

objectType - string

The type of the object, always Checklist.

id - string

The id of the checklist.

externalID - string

The external id of the checklist, or null if none. Unique among all checklists in your account.

projectID - string

The id of the project that contains the checklist.

ownerObjectType - string

The object type of the object that the checklist belongs to, for example BacklogItem.

ownerObjectID - string

The id of the object that the checklist belongs to.

name - string

The name of the checklist.

description - string

The description of the checklist, or null if none.

checklistItems - array of ChecklistItem objects

The checklist items in the checklist, empty if none.

Example 

{
  "objectType" : "Checklist",
  "id" : "729-5931-324",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "ownerObjectType" : "BacklogItem",
  "ownerObjectID" : "729-17823-1322",
  "name" : "Example checklist",
  "description" : "An example description.",
  "checklistItems" : [ {
    "objectType" : "ChecklistItem",
    "id" : "729-2397-323",
    "externalID" : null,
    "projectID" : "729-1321-1244",
    ...
  }, ... ]
}

ChecklistItem object

An item in a checklist.

Properties

objectType - string

The type of the object, always ChecklistItem.

id - string

The id of the checklist item.

externalID - string

The external id of the checklist item, or null if none. Unique among all checklist items in your account.

projectID - string

The id of the project that contains the checklist item.

checklistID - string

The id of the checklist that the checklist item belongs to.

name - string

The name of the checklist item.

description - string

The description of the checklist item, or null if none.

isChecked - boolean

True if the checklist item is checked, false if not.

Example 

{
  "objectType" : "ChecklistItem",
  "id" : "729-43612-129",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "checklistID" : "729-5931-324",
  "name" : "Example checklist item",
  "description" : "An example description.",
  "isChecked" : true
}

Comment object

A comment on another object.

Properties

objectType - string

The type of the object, always Comment.

id - string

The id of the comment.

externalID - string

The external id of the comment, or null if none. Unique among all comments in your account.

projectID - string

The id of the project that contains the comment.

ownerObjectType - string

The object type of the object that the comment belongs to, for example BacklogItem.

ownerObjectID - string

The id of the object that the comment belongs to.

parentCommentID - string

The id of the parent comment if this comment is a reply to another comment, or null if this comment is a top-level comment.

creatorID - string

The id of the person that created the comment, or null if none. This can refer to a Person or DeletedPerson object.

date - integer

The date when the comment was created, as the number of milliseconds since January 1, 1970 00:00:00 GMT.

text - string

The text of the comment, or null if the comment is empty.

replies - array of Comment objects

The replies to the comment, empty if none.

Example 

{
  "objectType" : "Comment",
  "id" : "729-3732-121",
  "externalID" : null,
  "projectID" : "729-1242-231",
  "ownerObjectType" : "BacklogItem",
  "ownerObjectID" : "729-3242-221",
  "parentCommentID" : null,
  "creatorID" : "729-3245-223",
  "date" : 1367860029000,
  "text" : "An example comment.",
  "replies" : [ {
  "objectType" : "Comment",
  "id" : "729-3732-341",
  "externalID" : null,
  "projectID" : "729-1242-231",
  "ownerObjectType" : "BacklogItem",
  "ownerObjectID" : "729-3242-221",
  "parentCommentID" : "729-3732-121",
  "creatorID" : "729-5984-423",
  "date" : 1368119229000,
  "text" : "An example reply.",
  "replies" : [ ]
  } ]
}

Commit object

A commit in a source control tool, such as GitHub.

Properties

objectType - string

The type of the object, always Commit.

id - string

The id of the commit.

externalID - string

The external id of the commit, or null if none. Unique among all commits in your account.

projectID - string

The id of the project that contains the commit.

ownerObjectType - string

The object type of the object that the commit belongs to, for example BacklogItem.

ownerObjectID - string

The id of the object that the commit belongs to.

date - integer

The date when the commit was made, as the number of milliseconds since January 1, 1970 00:00:00 GMT.

creatorID - string

The id of the person that did the commit. This can refer to a Person or DeletedPerson object.

repositoryName - string

The name of the repository, or null if none.

repositoryURL - string

The URL of the repository, or null if none.

revision - string

The repository revision after the commit.

message - string

The commit message (including the Scrumwise meta info).

commitURL - string

The URL of the commit, or null if none.

Example 

{
  "objectType" : "Commit",
  "id" : "729-4543-6286",
  "externalID" : null,
  "projectID" : "729-1453-441",
  "ownerObjectType" : "BacklogItem",
  "ownerObjectID" : "729-6538-337",
  "date" : 1367601020,
  "creatorID" : "729-9323-2333",
  "repositoryName" : "Example",
  "repositoryURL" : "https://github.com/..."
  "revision" : "8ec178ac8b2b385f3882553da18969a44331a6da",
  "message" : "An example message [Scrumwise item #938, used: 1.5 h, status: Done]",
  "commitURL" : "https://github.com/...",
}

CustomField object

A custom field.

Properties

objectType - string

The type of the object, always CustomField.

id - string

The id of the custom field.

projectID - string

The id of the project that contains the custom field.

name - string

The name of the custom field.

description - string

The description of the custom field, or null if none.

ownerObjectTypes - array of strings

The object types that have the custom field, at least one.

ownerBacklogItemTypes - array of strings

The backlog item types that have the custom field, or null if the custom field is for all backlog item types or the custom field is not for backlog items.

type - string

The type of the custom field. Can be Text (single line), Text (multiple lines), Checkbox, Integer, Number, Date, Link, Person, Team, Release, Sprint, Dropdown, Radio buttons, Checkboxes, List (single selection), or List (multiple selections).

unit - string

The unit of the custom field, or null if none.

options - array of strings

The options that the user can choose from in the custom field, or null if none.

isRequired - boolean

True if the custom field is required, false if not.

Example 

{
  "objectType" : "CustomField",
  "id" : "729-3421-906",
  "projectID" : "729-1321-1244",
  "name" : "Example custom field",
  "description" : "An example description.",
  "ownerObjectTypes" : [ "BacklogItem", "Task" ],
  "ownerBacklogItemTypes" : [ "Feature", "Bug" ],
  "type" : "Dropdown",
  "unit" : null,
  "options" : [ "Option 1", "Option 2", "Option 3" ],
  "isRequired" : false
}

CustomFieldValue object

The value of a custom field on an object.

Properties

objectType - string

The type of the object, always CustomFieldValue.

id - string

The id of the custom field value.

projectID - string

The id of the project that contains the custom field value.

customFieldID - string

The id of the custom field.

ownerObjectType - string

The object type of the object that has the custom field value, for example BacklogItem.

ownerObjectID - string

The id of the object that has the custom field value.

value - string

The value of the custom field on the object. This is always a string, regardless of the custom field type. If the custom field has no value on an object, there is no corresponding CustomFieldValue object, so absence of a value is represented by absence of a CustomFieldValue object, not a value of null.

Example 

{
  "objectType" : "CustomFieldValue",
  "id" : "729-4233-322",
  "projectID" : "729-1321-1244",
  "customFieldID" : "729-5334-644",
  "ownerObjectType" : "BacklogItem",
  "ownerObjectID" : "729-3242-221",
  "value" : "16.75"
}

Data object

The object that is returned as the result of the getData method.

Properties

objectType - string

The type of the object, always Data.

persons - array of Person objects

The persons in your account, or null if not included.

deletedPersons - array of DeletedPerson objects

The deleted persons in your account, empty if none, or null if not included.

projects - array of Project objects

The returned projects, empty if none.

Example 

{
  "objectType" : "Data",
  "persons" : null,
  "deletedPersons" : null,
  "projects" : [ {
    "objectType" : "Project",
    "id" : "729-11230-1",
    "externalID" : null,
    "name" : "Project 1",
    ...
  }, {
    "objectType" : "Project",
    "id" : "729-44335-243",
    "externalID" : null,
    "name" : "Project 2",
    ...
  } ]
}

DeletedPerson object

A deleted person.

When a person has been deleted, the basic information about the person is kept in this object. This way, the person can continue to be referenced from other objects. The DeletedPerson object has the same id as the Person object had for the person.

Properties

objectType - string

The type of the object, always DeletedPerson.

id - string

The id of the person. This is the same id as the Person object had for the person before the person was deleted.

externalID - string

The external id of the person, or null if none.

firstName - string

The first name of the person.

lastName - string

The last name of the person, or null if none.

nickname - string

The nickname of the person, or null if none.

emailAddress - string

The email address of the person.

phone - string

The phone info of the person, or null if none.

im - string

The instant messaging info of the person, or null if none.

description - string

The description of the person, or null if none.

photoURL - string

The URL of the photo of the person, or null if none.

Example 

{
  "objectType" : "DeletedPerson",
  "id" : "729-14538-213",
  "externalID" : null,
  "firstName" : "Chris",
  "lastName" : "Robertson",
  "nickname" : null,
  "emailAddress" : "chris@example.com",
  "phone" : null,
  "im" : null,
  "description" : null,
  "photoURL" : "https://www.scrumwise.com/service/resource..."
}

Error object

The response object that you will receive if a request fails.

Properties

objectType - string

The type of the object, always Error.

errorID - string

A string that identifies the type of error, for example InvalidParameter. You can see the possible error ids here.

errorMessage - string

An error message.

Example 

{
  "objectType" : "Error",
  "errorID" : "ObjectNotFound",
  "errorMessage" : "There is no project with the id 729-11230-2."
}

File object

A file or a folder in a project.

Properties

objectType - string

The type of the object, always File.

id - string

The id of the file.

externalID - string

The external id of the file, or null if none. Unique among all files in your account.

projectID - string

The id of the project that contains the file.

parentFolderID - string

The id of the folder that contains the file, or null if the file is not contained in any folder.

isFolder - boolean

True if this is a folder, false if it is a file.

name - string

The name of the file, or null if none. Cannot be null if this is a folder.

description - string

The description of the file, or null if none.

creatorID - string

The id of the person that created the file, or null if none. This can refer to a Person or DeletedPerson object.

date - integer

The date when the file was created, as the number of milliseconds since January 1, 1970 00:00:00 GMT.

isArchived - boolean

True if the file is archived, false if not.

fileName - string

The file name of the file, or null if none or if this is a folder.

thumbnailURL - string

The URL of a preview image of the file, or null if not available or if this is a folder.

url - string

The URL of the file, or null if this is a folder.

tagIDs - array of strings

The ids of the tags on the file, empty if none.

comments - array of Comments objects

The comments on the file, empty if none, or null if not included.

files - array of File objects

The files in this folder, empty if none or if this is not a folder.

Example

{
  "objectType" : "File",
  "id" : "729-3532-221",
  "externalID" : null,
  "projectID" : "729-3251-651",
  "parentFolderID" : null,
  "isFolder" : false,
  "name" : "Example file",
  "description" : "An example description.",
  "creatorID" : "729-5984-423",
  "date" : 1368119229000,
  "isArchived" : false,
  "fileName" : "Example.png",
  "thumbnailURL" : "https://www.scrumwise.com/service/resource...",
  "url" : "https://www.scrumwise.com/service/resource...",
  "tagIDs" : [ "729-10820-446", "729-10820-226" ],
  "comments" : null,
  "files" : [ ]
}

Message object

A message in the message board of a project.

Properties

objectType - string

The type of the object, always Message.

id - string

The id of the message.

externalID - string

The external id of the message, or null if none. Unique among all messages in your account.

projectID - string

The id of the project that contains the message.

title - string

The title of the message.

text - string

The text the message, or null if none.

link - string

The link URL of the message, or null if none.

type - string

The type of the message, or null if none. Can be Announcement, Information, Question, Idea, To do, or Other.

creatorID - string

The id of the person that created the message, or null if none. This can refer to a Person or DeletedPerson object.

date - integer

The date when the message was created, as the number of milliseconds since January 1, 1970 00:00:00 GMT.

color - string

The color of the message, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

isArchived - boolean

True if the message is archived, false if not.

tagIDs - array of strings

The ids of the tags on the message, empty if none.

checklists - array of Checklist objects

The checklists on the message, empty if none, or null if not included.

comments - array of Comments objects

The comments on the message, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the message, empty if none, or null if not included.

Example 

{
  "objectType" : "Message",
  "id" : "729-8333-622",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "title" : "Example message",
  "text" : "An example text.",
  "link" : "http://www.example.com",
  "type" : "Announcement",
  "creatorID" : "729-438-7938",
  "date" : 1540456717184,
  "color" : "Green",
  "isArchived" : false,
  "tagIDs" : [ "729-10820-446", "729-10820-226" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null
}

Person object

A person.

Properties

objectType - string

The type of the object, always Person.

id - string

The id of the person.

externalID - string

The external id of the person, or null if none. Unique among all persons in your account.

firstName - string

The first name of the person.

lastName - string

The last name of the person, or null if none.

nickname - string

The nickname of the person, or null if none.

emailAddress - string

The email address of the person.

phone - string

The phone info of the person, or null if none.

im - string

The instant messaging info of the person, or null if none.

description - string

The description of the person, or null if none.

photoURL - string

The URL of the photo of the person, or null if none.

isActivated - boolean

True if the person has activated his/her account, false if not.

isAdministrator - boolean

True if the person is administrator, false if not.

Example 

{
  "objectType" : "Person",
  "id" : "729-3156-1343",
  "externalID" : null,
  "firstName" : "John",
  "lastName" : "Smith",
  "nickname" : null,
  "emailAddress" : "john@example.com",
  "phone" : null,
  "im" : null,
  "description" : null,
  "photoURL" : "https://www.scrumwise.com/service/resource...",
  "isActivated" : true,
  "isAdministrator" : false
}

Project object

A project.

Properties

objectType - string

The type of the object, always Project.

id - string

The id of the project.

externalID - string

The external id of the project, or null if none. Unique among all projects in your account.

name - string

The name of the project.

description - string

The description of the project, or null if none.

link - string

The link URL of the project, or null if none.

status - string

The status of the project. Can be Active or Archived.

roughEstimateUnit - string

The unit used for rough estimates in the project. Can be Points, Days, or Hours.

detailedEstimateUnit - string

The unit used for detailed estimates in the project. Can be Points, Days, or Hours.

timeTrackingUnit - string

The unit used for detailed time tracking in the project. Can be Points, Days, or Hours.

checklists - array of Checklist objects

The checklists on the project, empty if none, or null if not included.

comments - array of Comment objects

The comments on the project, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the project, empty if none, or null if not included.

customFields - array of CustomField objects

The custom fields in the project, empty if none, or null if not included.

tags - array of Tag objects

The tags in the project, empty if none, or null if not included.

productOwnerIDs - array of strings

The ids of the persons that are product owners in the project, empty if none.

stakeholderIDs - array of strings

The ids of the persons that are stakeholders in the project, empty if none.

teams - array of Team objects

The teams in the project, empty if none, or null if not included.

messages - array of Message objects

The messages in the project, empty if none, or null if not included.

backlogs - array of Backlog objects

The backlogs in the project, at least one, or null if not included.

backlogItems - array of BacklogItem objects

The backlog items in the project, empty if none, or null if not included. Note: This property contains all backlog items in the project, regardless of which backlogs and backlog lists they belong to. To get the backlog items organized by backlogs and backlog lists, use the backlogs property instead.

releases - array of Release objects

The releases in the project, empty if none, or null if not included.

sprints - array of Sprint objects

The sprints in the project, empty if none, or null if not included.

boards - array of Board objects

The boards in the project, empty if none, or null if not included.

retrospectives - array of Retrospective objects

The retrospectives in the project, empty if none, or null if not included.

files - array of File objects

The files in the project, empty if none, or null if not included.

relationships - array of Relationship objects

The relationships in the project, empty if none, or null if not included.

Example 

{
  "objectType" : "Project",
  "id" : "729-11230-1",
  "externalID" : null,
  "name" : "Project 1",
  "description" : null,
  "link" : "http://www.example.com",
  "status" : "Active",
  "roughEstimateUnit" : "Points",
  "detailedEstimateUnit" : "Days",
  "timeTrackingUnit" : "Hours",
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "customFields" : null,
  "tags" : null,
  "productOwnerIDs" : [ "729-334-1" ],
  "stakeholderIDs" : [ "729-4151-1", "729-8107-6" ],
  "teams" : null,
  "messages" : null,
  "backlogs" : null,
  "backlogItems" : null,
  "releases" : null,
  "sprints" : null,
  "boards" : null,
  "retrospectives" : null,
  "files" : null,
  "relationships" : null
}

Relationship object

A relationship between two objects.

Properties

objectType - string

The type of the object, always Relationship.

id - string

The id of the relationship.

externalID - string

The external id of the relationship, or null if none. Unique among all relationships in your account.

projectID - string

The id of the project that contains the relationship.

type - string

The type of the relationship. Can be Must be done after, Must be done before, Is dependent on, Is dependency for, Is blocked by, Is blocking, Is bug on, Has bug, Is duplicate of, Has duplicate, or Is related to.

fromObjectType - string

The object type of the object that the relationship starts at, for example BacklogItem.

fromObjectID - string

The id of the object that the relationship starts at.

toObjectType - string

The object type of the object that the relationship ends at, for example BacklogItem.

toObjectID - string

The id of the object that the relationship ends at.

description - string

The description of the relationship, or null if none.

Example

{
  "objectType" : "Relationship",
  "id" : "729-8641-15",
  "externalID" : null,
  "projectID" : "729-3251-651",
  "type" : "Is dependent on",
  "fromObjectType" : "BacklogItem",
  "fromObjectID" : "729-14333-430",
  "toObjectType" : "BacklogItem",
  "toObjectID" : "729-19032-942",
  "description" : "An example description."
}

Release object

A release.

Properties

objectType - string

The type of the object, always Release.

id - string

The id of the release.

externalID - string

The external id of the release, or null if none. Unique among all releases in your account.

projectID - string

The id of the project that contains the release.

name - string

The name of the release.

description - string

The description of the release, or null if none.

link - string

The link URL of the release, or null if none.

startDate - string

The start date of the release, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

releaseDate - string

The planned release date of the release, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

status - string

The status of the release. Can be In planning, In progress, or Completed.

bestCaseVelocityPerWeek - number

The best-case velocity per week of the release, in the unit used for rough estimates in the project, or -1 if none.

expectedVelocityPerWeek - number

The expected velocity per week of the release, in the unit used for rough estimates in the project, or -1 if none.

worstCaseVelocityPerWeek - number

The worst-case velocity per week of the release, in the unit used for rough estimates in the project, or -1 if none.

customFieldValues - array of CustomFieldValue objects

The custom field values on the release, empty if none, or null if not included.

tagIDs - array of strings

The ids of the tags on the release, empty if none.

checklists - array of Checklist objects

The checklists on the release, empty if none, or null if not included.

comments - array of Comment objects

The comments on the release, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the release, empty if none, or null if not included.

assignedBacklogItemIDs - array of strings

The ids of the backlog items that are assigned to the release, empty if none.

Example 

{
  "objectType" : "Release",
  "id" : "729-2462-323",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "name" : "Example release",
  "description" : "An example description.",
  "link" : "http://www.example.com",
  "startDate" : "2019-09-06",
  "releaseDate" : "2019-12-10",
  "status" : "In progress",
  "bestCaseVelocityPerWeek" : 35.0,
  "expectedVelocityPerWeek" : 29.0,
  "worstCaseVelocityPerWeek" : -1,
  "customFieldValues" : null,
  "tagIDs" : [ "729-10820-446", "729-10820-226" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "assignedBacklogItemIDs" : [ "729-3056-422", "729-4333-633", "729-7252-65", ... ]
}

Result object

The response object that you will receive when a request succeeds.

Properties

objectType - string

The type of the object, always Result.

dataVersion - integer

The data version that your data had when the result was created. The data in your account has a version number that is increased whenever any change is made to the data. Thus, the data version uniquely identifies the exact state of your data when the result was created.

result - (Type depends on the method)

The result itself, as specified for the method. This is either a primitive type, an object, or an array of objects.

Example 

{
  "objectType" : "Result",
  "dataVersion" : 50742,
  "result" : {
    "objectType" : "Data",
    "persons" : null,
    "deletedPersons" : null,
    "projects" : [ {
      "objectType" : "Project",
      "id" : "729-11230-1",
      "externalID" : null,
      "name" : "Project 1",
      ...
    }, {
      "objectType" : "Project",
      "id" : "729-44335-243",
      "externalID" : null,
      "name" : "Project 2",
      ...
    } ]
  }
}

Retrospective object

A retrospective.

Properties

objectType - string

The type of the object, always Retrospective.

id - string

The id of the retrospective.

externalID - string

The external id of the retrospective, or null if none. Unique among all retrospectives in your account.

projectID - string

The id of the project that contains the retrospective.

name - string

The name of the retrospective.

description - string

The description of the retrospective, or null if none.

creatorID - string

The id of the person that created the retrospective, or null if none. This can refer to a Person or DeletedPerson object.

creationDate - integer

The date when the retrospective was created, as the number of milliseconds since January 1, 1970 00:00:00 GMT.

color - string

The color of the retrospective, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

isArchived - boolean

True if the retrospective is archived, false if not.

tagIDs - array of strings

The ids of the tags on the retrospective, empty if none.

checklists - array of Checklist objects

The checklists on the retrospective, empty if none, or null if not included.

comments - array of Comments objects

The comments on the retrospective, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the retrospective, empty if none, or null if not included.

columns - array of RetrospectiveColumn objects

The columns in the retrospective, at least 2.

Example 

{
  "objectType" : "Retrospective",
  "id" : "729-8333-622",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "name" : "Example retrospective",
  "description" : "An example text.",
  "creatorID" : "729-438-7938",
  "creationDate" : 1540456717184,
  "color" : "Green",
  "isArchived" : false,
  "tagIDs" : [ "729-10820-446", "729-10820-226" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "columns" : [ {
    "objectType" : "RetrospectiveColumn",
    "name" : "Example column",
    "color" : null,
    "cards" : [ {
      "objectType" : "RetrospectiveCard",
      "id" : "729-2092-398",
      ...
    }, {
      "objectType" : "RetrospectiveCard",
      "id" : "729-3098-488",
      ...
    }, ... ]
  }, ... ]
}

RetrospectiveCard object

A card in a retrospective.

Properties

objectType - string

The type of the object, always RetrospectiveCard.

id - string

The id of the card.

externalID - string

The external id of the card, or null if none. Unique among all retrospective cards in your account.

projectID - string

The id of the project that contains the card.

retrospectiveID - string

The id of the retrospective that contains the card.

columnNum - string

The column number that the card is in, in the retrospective, starting from 1.

name - string

The name of the card.

description - string

The description of the card, or null if none.

creatorID - string

The id of the person that created the card, or null if none. This can refer to a Person or DeletedPerson object.

creationDate - integer

The date when the card was created, as the number of milliseconds since January 1, 1970 00:00:00 GMT.

color - string

The color of the card, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

tagIDs - array of strings

The ids of the tags on the card, empty if none.

checklists - array of Checklist objects

The checklists on the card, empty if none, or null if not included.

comments - array of Comments objects

The comments on the card, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the card, empty if none, or null if not included.

Example 

{
  "objectType" : "RetrospectiveCard",
  "id" : "729-2089-232",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "retrospectiveID" : "729-8333-622",
  "columnNum" : 2,
  "name" : "Example card",
  "description" : "An example text.",
  "creatorID" : "729-438-7938",
  "creationDate" : 1540456717184,
  "color" : "Green",
  "tagIDs" : [ "729-10820-446", "729-10820-226" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null
}

RetrospectiveColumn object

A column in a retrospective.

Properties

objectType - string

The type of the object, always RetrospectiveColumn.

name - string

The name of the column.

color - string

The color of the column, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

cards - array of RetrospectiveCard objects

The retrospective cards in the column, empty if none.

Example 

{
  "objectType" : "RetrospectiveColumn",
  "name" : "Example column",
  "color" : null,
  "cards" : [ {
    "objectType" : "RetrospectiveCard",
    "id" : "729-2092-398",
    ...
  }, {
    "objectType" : "RetrospectiveCard",
    "id" : "729-3098-488",
    ...
  }, ... ]
}

Sprint object

A sprint.

Properties

objectType - string

The type of the object, always Sprint.

id - string

The id of the sprint.

externalID - string

The external id of the sprint, or null if none. Unique among all sprints in your account.

projectID - string

The id of the project that contains the sprint.

name - string

The name of the sprint.

description - string

The description of the sprint, or null if none.

link - string

The link URL of the sprint, or null if none.

startDate - string

The start date of the sprint, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

endDate - string

The end date of the sprint, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

boardID - string

The id of the board that the sprint uses, or null if none.

status - string

The status of the sprint. Can be In planning, In progress, Completed, or Aborted.

isArchived - boolean

True if the sprint is archived, false if not.

customFieldValues - array of CustomFieldValue objects

The custom field values on the sprint, empty if none, or null if not included.

tagIDs - array of strings

The ids of the tags on the sprint, empty if none.

checklists - array of Checklist objects

The checklists on the sprint, empty if none, or null if not included.

comments - array of Comments objects

The comments on the sprint, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the sprint, empty if none, or null if not included.

teamSprintParticipations - array of TeamSprintParticipation objects

For each team that participates in the sprint, a TeamSprintParticipation object, empty if no teams participate.

Example 

{
  "objectType" : "Sprint",
  "id" : "729-8333-622",
  "externalID" : null,
  "projectID" : "729-1321-1244",
  "name" : "Example sprint",
  "description" : "An example description.",
  "link" : "http://www.example.com",
  "startDate" : "2019-05-06",
  "endDate" : "2019-05-17",
  "boardID" : "729-2351-553",
  "status" : "In progress",
  "isArchived" : false,
  "customFieldValues" : null,
  "tagIDs" : [ "729-10820-446", "729-10820-226" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "teamSprintParticipations" : [ {
    "objectType" : "TeamSprintParticipation",
    "id" : "729-1325-20_8333-622",
    "projectID" : "729-1321-1244",
    "teamID" : "729-1325-20",
    "sprintID" : "729-8333-622",
    "availableTime" : 25.0,
    "assignedBacklogItemIDs" : [ "729-3056-422", "729-4333-633", "729-7252-65", ... ]
  }, {
    "objectType" : "TeamSprintParticipation",
    "id" : "729-3421-333_8333-622",
    "projectID" : "729-1321-1244",
    "teamID" : "729-3421-333",
    "sprintID" : "729-8333-622",
    "availableTime" : 35.0,
    "assignedBacklogItemIDs" : [ "729-1064-123", "729-3056-722", "729-3057-131", ... ]
  } ]
}

Tag object

A tag.

Properties

objectType - string

The type of the object, always Tag.

id - string

The id of the tag.

externalID - string

The external id of the tag, or null if none. Unique among all tags in your account.

projectID - string

The id of the project that contains the tag.

name - string

The name of the tag.

description - string

The description of the tag, or null if none.

color - string

The color of the tag. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray

Example 

{
  "objectType" : "Tag",
  "id" : "729-11027-933",
  "externalID" : null,
  "projectID" : "729-13422-1222",
  "name" : "Tag 1",
  "description" : "An example description.",
  "color" : "Red"
}

Task object

A task in a backlog item.

Properties

objectType - string

The type of the object, always Task.

id - string

The id of the task.

externalID - string

The external id of the task, or null if none. Unique among all tasks in your account.

taskNumber - integer

The task number of the task, starting from 1. Unique among all tasks in your account.

projectID - string

The id of the project that contains the task.

backlogItemID - string

The id of the backlog item that the task belongs to.

name - string

The name of the task.

description - string

The description of the task, or null if none.

link - string

The link URL of the task, or null if none.

color - string

The color of the task, or null if none. Can be Red, Light red, Dark orange, Orange, Yellow, Light green, Green, Dark green, Light blue, Blue, Dark blue, Purple, Pink, Light brown, Dark brown, Light gray, or Dark gray.

creationDate - integer

The date where the task was created, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if not available.

status - string

The status of the task. Can be To do, In progress, To test, or Done.

toDoDate - integer

The date where the task was set to status To do, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the task has not had this status or the date is not available.

inProgressDate - integer

The date where the task was set to status In progress, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the task has not had this status or the date is not available.

toTestDate - integer

The date where the task was set to status To test, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the task has not had this status or the date is not available.

doneDate - integer

The date where the task was set to status Done, as the number of milliseconds since January 1, 1970 00:00:00 GMT, or null if the task has not had this status or the date is not available.

boardColumnID - string

The id of the board column that the task is in, in the board that its owner item is assigned to, or null if none.

estimate - number

The estimate of the task, in the unit used for detailed estimates in the project, or -1 if none.

usedTime - number

The time used on the task, or -1 if not specified. If detailed time tracking is used, this is in the unit used for detailed time tracking in the project, else the unit used for detailed estimates.

remainingWork - number

The remaining work on the task, in the unit used for detailed estimates in the project, or -1 if not specified.

assignedPersonIDs - array of strings

The ids of the persons that the task is assigned to, empty if none. This can refer to Person or DeletedPerson objects.

dueDate - string

The due date of the task, as a string in the format YYYY-MM-DD, for example "2019-10-27", or null if none.

customFieldValues - array of CustomFieldValue objects

The custom field values on the task, empty if none, or null if not included.

tagIDs - array of strings

The ids of the tags on the task, empty if none.

checklists - array of Checklist objects

The checklists on the task, empty if none, or null if not included.

comments - array of Comment objects

The comments on the task, empty if none, or null if not included.

attachments - array of Attachment objects

The attachments on the task, empty if none, or null if not included.

timeEntries - array of TimeEntry objects

The time entries on the task, empty if none, or null if not included.

commits - array of Commit objects

The commits on the task, empty if none, or null if not included.

Example 

{
  "objectType" : "Task",
  "id" : "729-3322-69378",
  "externalID" : null,
  "taskNumber" : 1325,
  "projectID" : "729-11230-1",
  "backlogItemID" : "729-6743-353",
  "name" : "Example task 1",
  "description" : "An example description.",
  "link" : "http://www.example.com",
  "color" : "Blue",
  "creationDate" : 1547836680000,
  "status" : "In progress",
  "toDoDate" : 1547836680000,
  "inProgressDate" : 1548081480000,
  "toTestDate" : null,
  "doneDate" : null,
  "boardColumnID" : "729-4765-83",
  "estimate" : 10.25,
  "usedTime" : 4.5,
  "remainingWork" : 5.0,
  "assignedPersonIDs" : [ "729-7654-243" ],
  "dueDate" : null,
  "customFieldValues" : null,
  "tagIDs" : [ "729-14820-466", "729-12820-336" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "timeEntries" : null,
  "commits" : null
}

Team object

A team.

Properties

objectType - string

The type of the object, always Team.

id - string

The id of the team.

externalID - string

The external id of the team, or null if none. Unique among all teams in your account.

projectID - string

The id of the project that contains the team.

name - string

The name of the team.

description - string

The description of the team, or null if none.

teamMemberIDs - array of strings

The ids of the persons that are members of the team, empty if none.

Example 

{
  "objectType" : "Team",
  "id" : "729-11234-15",
  "externalID" : null,
  "projectID" : "729-11230-1",
  "name" : "Team 1",
  "description" : null,
  "teamMemberIDs" : [ "729-4151-441", "729-8107-64", "729-3465-132", "729-4355-27", ... ]
}

TeamSprintParticipation object

An object that contains information about a team’s participation in a sprint.

Properties

objectType - string

The type of the object, always TeamSprintParticipation.

id - string

The id of the TeamSprintParticipation.

projectID - string

The id of the project that contains the TeamSprintParticipation.

teamID - string

The id of the team.

sprintID - string

The id of the sprint.

availableTime - number

The available time for the team in the sprint, in the unit used for detailed estimates in the project, or -1 if not specified.

assignedBacklogItemIDs - array of strings

The ids of the backlog items that are assigned to the team in the sprint, empty if none.

Example 

{
  "objectType" : "TeamSprintParticipation",
  "id" : "729-1325-20_8333-622",
  "projectID" : "729-1321-1244",
  "teamID" : "729-1325-20",
  "sprintID" : "729-8333-622",
  "availableTime" : 25.0,
  "assignedBacklogItemIDs" : [ "729-3056-422", "729-4333-633", "729-7252-65", ... ]
}

TimeEntry object

A time entry on another object, specifying some time that was used on the object.

Properties

objectType - string

The type of the object, always TimeEntry.

id - string

The id of the time entry.

externalID - string

The external id of the time entry, or null if none. Unique among all time entries in your account.

projectID - string

The id of the project that contains the time entry.

ownerObjectType - string

The object type of the object that the time was used on, for example BacklogItem.

ownerObjectID - string

The id of the object that the time was used on.

date - string

The date on which the time was used, as a string in the format YYYY-MM-DD, for example "2019-10-27".

personID - string

The id of the person that used the time. This can refer to a Person or DeletedPerson object.

description - string

The description of the used time, or null if none.

usedTime - number

The amount of time that was used, in the unit used for detailed time tracking in the project.

customFieldValues - array of CustomFieldValue objects

The custom field values on the time entry, empty if none, or null if not included.

Example 

{
  "objectType" : "TimeEntry",
  "id" : "729-11305-19",
  "externalID" : null,
  "projectID" : "729-11230-1",
  "ownerObjectType" : "BacklogItem",
  "ownerObjectID" : "729-11304-31",
  "date" : "2019-05-06",
  "personID" : "729-4334-232",
  "description" : "An example description.",
  "usedTime" : 2.5,
  "customFieldValues" : null
}

Errors

InvalidRequest

The request is not valid.

InvalidURL

The request URL is not valid.

AuthenticationRequired

The HTTP Basic authentication info is missing.

InvalidAuthenticationInfo

The HTTP Basic authentication info is not valid.

InvalidUserEmailAddress

The username that you have specified in the HTTP Basic authentication is not a valid email address of a user in your account.

InvalidAPIKey

The password that you have specified in the HTTP Basic authentication is not a valid API key.

APINotAvailable

The API is not available right now.

DuringMaintenance

The API is not available right now due to maintenance.

InternalServerError

An internal server error has occurred.

CompanyAccountClosed

Your Scrumwise company account has been closed.

APIAccessNotAllowed

Your access to the API has been turned off. Please contact us at support@scrumwise.com.

APIBusy

The API is too busy to handle your request right now. Please try again later.

APILimitReached

You have reached a limit on the number of requests you can make in the API. Please contact us at support@scrumwise.com.

TooManyOngoingRequests

You have too many ongoing requests to the API.

InvalidMethodName

The API has no method with the name you have specified.

InvalidParameter

A parameter is invalid.

MissingParameter

A required parameter is missing.

ObjectNotFound

An object that you have specified does not exist.

RequirementNotSatisfied

A requirement of the method is not satified.

UserCannotAccessProject

The user that you are performing the request on behalf of does not have permission to access the project.

UserHasInsufficientPermissions

The user that you are performing the request on behalf of does not have sufficient permissions to perform this action.

ObjectWithExternalIDAlreadyExists

There is already an object of the particular object type that has the external id that you have specified.

RequestAlreadyExecuted

A request with the specified request id has already been executed successfully.

RequiredDataVersionNotMatching

The current data version of your account does not match the required data version that you have specified.

API Changes

The current version of the API is version 1.11.

Version 1.11

Version 1.10

Version 1.9

Version 1.8

Version 1.7

Version 1.6

  • Added the type Epic as a possible value of BacklogItem.type.
  • Added the properties BacklogItem.parentEpicID and BacklogItem.childBacklogItems.
  • Added the parameter parentEpicID in the addBacklogItem method.

Version 1.5

Version 1.4

Version 1.3

  • Added the parameters estimate and estimateUnit in the addBacklogItem method.
  • Added the parameters estimate and estimateUnit in the addTask method.
  • Added the methods setBacklogItemAssignedPersonID and setTaskAssignedPersonID.
  • The addTask method now allows a task to be added to a backlog item with status below or equal to Done. Previously, the backlog item status had to be New or Ready for estimation.

Version 1.2

Version 1.1

  • Added the Release object.
  • Added the properties Project.releases and BacklogItem.releaseID.
  • Added the status Released as a possible value of BacklogItem.status.
  • Added the method setReleaseExternalID.