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,
      "tags" : null,
      "productOwnerIDs" : [ "729-334-1" ],
      "stakeholderIDs" : [ "729-4151-1", "729-8107-6" ],
      "teams" : null,
      "backlogItems" : [ {
        "objectType" : "BacklogItem",
        "id" : "729-11304-21",
        "externalID" : null,
        "itemNumber" : 214,
        "projectID" : "729-11230-1",
        "name" : "Backlog item 1",
        "description" : null,
        "link" : null,
        "priority" : null,
        "type" : "Feature",
        "color" : "Blue",
        "creatorID" : "729-3232-553",
        "releaseID" : null,
        "status" : "New",
        "roughEstimate" : -1.0,
        "estimate" : -1.0,
        "usedTime" : -1.0,
        "remainingWork" : -1.0,
        "sprintID" : null,
        "teamID" : null,
        "boardID" : null,
        "boardColumnID" : null,
        "assignedPersonIDs" : [ ],
        "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",
          "status" : "To do",
          "boardColumnID" : null,
          "estimate" : -1.0,
          "usedTime" : -1.0,
          "remainingWork" : -1.0,
          "assignedPersonIDs" : [ ],
          "tagIDs" : [ ],
          "checklists" : null,
          "comments" : null,
          "attachments" : null,
          "timeEntries" : null,
          "commits" : null
        }, ... ]
      }, ... ],
      "releases" : null,
      "sprints" : null,
      "boards" : 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.

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

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

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 Feature, Bug, Spike, or Other.

roughEstimate - number

The 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.

estimate - number

The 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.

index - integer

The index to add the backlog item at in the list of all backlog items in the project, or -1 to add the backlog item at the end of the list. Note: This is the index among all backlog items in the project, 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 "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.

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
}

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.

Requirements

The backlog item is not allowed to have any tasks (if it has tasks, the assigned person must be set on each of the tasks instead). If unassigning the backlog item, the backlog item must have status below or equal to To do.

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
}

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
}

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
}

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
}

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 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
}

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

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

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
}

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, Release, Sprint, BacklogItem, or Task.

ownerObjectType - 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
}

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,
      "tags" : null,
      "productOwnerIDs" : [ "729-334-1" ],
      "stakeholderIDs" : [ "729-4151-1", "729-8107-6" ],
      "teams" : null,
      "backlogItems" : [ {
        "objectType" : "BacklogItem",
        "id" : "729-11304-21",
        "externalID" : null,
        "itemNumber" : 214,
        "projectID" : "729-11230-1",
        "name" : "Backlog item 1",
        "description" : null,
        "link" : null,
        "priority" : null,
        "type" : "Feature",
        "color" : "Blue",
        "creatorID" : "729-3232-322",
        "releaseID" : null,
        "status" : "New",
        "roughEstimate" : -1.0,
        "estimate" : -1.0,
        "usedTime" : -1.0,
        "remainingWork" : -1.0,
        "sprintID" : null,
        "teamID" : null,
        "boardID" : null,
        "boardColumnID" : null,
        "assignedPersonIDs" : [ ],
        "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",
          "status" : "To do",
          "boardColumnID" : null,
          "estimate" : -1.0,
          "usedTime" : -1.0,
          "remainingWork" : -1.0,
          "assignedPersonIDs" : [ ],
          "tagIDs" : [ ],
          "checklists" : null,
          "comments" : null,
          "attachments" : null,
          "timeEntries" : null,
          "commits" : null
        }, ... ]
      }, ... ],
      "releases" : null,
      "sprints" : null,
      "boards" : 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
}

Person methods

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
}

Release methods

setReleaseExternalID

Sets the external id of a release.

Parameters

releaseID - string

The id of the release.

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/setReleaseExternalID
  -k -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d releaseID=729-15367-3125
  -d externalID=RE86536527
{
  "objectType" : "Result",
  "dataVersion" : 50842,
  "result" : null
}

Sprint methods

setSprintExternalID

Sets the external id of a sprint.

Parameters

sprintID - string

The id of the sprint.

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/setSprintExternalID -k
  -u bob@example.com:69C0A6A9E957B6398BD8C62F3B67C95005CA...
  -d sprintID=729-10367-745
  -d externalID=SP86486527
{
  "objectType" : "Result",
  "dataVersion" : 50810,
  "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 new external id of the project, or null if none. Must be unique among all projects 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 Release, Sprint, BacklogItem, or Task.

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 Release, Sprint, BacklogItem, or Task.

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.

Requirements

The backlog item must have status below or equal to Done.

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.

Requirements

The backlog item that contains the task must have status below Sprint completed.

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
}

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.

Requirements

If unassigning the task, the task must have status below or equal to To do.

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
}

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
}

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
}

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

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=TI34980254
{
  "objectType" : "Result",
  "dataVersion" : 50812,
  "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..."
}

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.

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

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.

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.

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.

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.

Example

{
  "objectType" : "BacklogItem",
  "id" : "729-33220-627",
  "externalID" : null,
  "itemNumber" : 2149,
  "projectID" : "729-11230-132",
  "name" : "Example backlog item 1",
  "description" : "An example description.",
  "link" : "http://www.example.com",
  "priority" : "High",
  "type" : "Feature",
  "color" : "Blue",
  "creatorID" : "729-32144-2210",
  "releaseID" : "729-3490-4392",
  "status" : "In progress",
  "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",
  "assignedPersonIDs" : [ "729-5444-343" ],
  "tagIDs" : [ "729-14820-466", "729-6893-337" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "timeEntries" : null,
  "commits" : null,
  "tasks" : null,
}

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 not available. 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.

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/...",
}

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."
}

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.

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.

backlogItems - array of BacklogItem objects

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

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.

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,
  "tags" : null,
  "productOwnerIDs" : [ "729-334-1" ],
  "stakeholderIDs" : [ "729-4151-1", "729-8107-6" ],
  "teams" : null,
  "backlogItems" : null,
  "releases" : null,
  "sprints" : null,
  "boards" : null
}

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 "2013-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 "2013-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.

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" : "2013-09-06",
  "releaseDate" : "2013-12-10",
  "status" : "In progress",
  "bestCaseVelocityPerWeek" : 35.0,
  "expectedVelocityPerWeek" : 29.0,
  "worstCaseVelocityPerWeek" : -1,
  "tagIDs" : [ "729-10820-446", "729-10820-226" ],
  "checklists" : null,
  "comments" : null,
  "attachments" : null,
  "assignedBacklogItemIDs" : [ "729-3056-422", "729-4333-633", "729-7252-65", "729-6434-566" ]
}

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",
      ...
    } ]
  }
}

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 "2013-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 "2013-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.

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" : "2013-05-06",
  "endDate" : "2013-05-17",
  "boardID" : "729-2351-553",
  "status" : "In progress",
  "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", "729-6434-566" ]
  }, {
    "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", "729-4309-471" ]
  } ]
}

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.

status - string

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

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.

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",
  "status" : "In progress",
  "boardColumnID" : "729-4765-83",
  "estimate" : 10.25,
  "usedTime" : 4.5,
  "remainingWork" : 5.0,
  "assignedPersonIDs" : [ "729-7654-243" ],
  "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", "729-6544-221" ]
}

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", "729-6434-566" ]
}

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 "2013-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 id of the person that used the time. 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.

Example

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

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.4.

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.