Loading
Back to previous page

Card API

Cards

Card resources are located by issuing a GET request to the server with the card's number as a parameter.

In Mingle 3.0, we have updated our our APIs extensively. One main change to note is that the new Card API has been updated to always use the card number to identify a card. Card id will no longer be used. If you wish to upgrade to use the latest version of the API (v2) with Mingle 3.0, please ensure you change all requests to use card number, not card id, before upgrading. It is important to make this change because if you do not specify the correct card number you may unintentionally update the wrong card and damage your data.

You can continue to use the previous version of the API with Mingle 3.0 although you will need to explicitly reference this by adding an API version to the requested URL, e.g. http://localhost:8080/api/v1/projects/your_project/cards.xml.

Before you manipulate cards using the API, we recommend that you familiarize yourself with some key concepts related to cards like card types and card properties. Click here to learn more about card types. Click here to learn more about card properties.

Please note that all the API resources and examples refer to v2 of the API. If you would like information on v1 of the API please refer to older versions of the help that can be found at the ThoughtWorks Studios website.

Please note that all POST and PUT requests must be in XML format by default. This is not illustrated in the examples here. To specify parameters as shown in the examples you will have to set the request header for Content-Type to "application/x-www-form-urlencoded".

Structure of a card resource

The structure of a card will completely depend on your project and how you have configured your properties. That said, all cards in all projects in Mingle have a few default attributes. In addition to these you will have an attribute for each property definition that you define for your project.

The default attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value. System generated fields like id, number, created_on etc. are provided only as information about the card and cannot be updated through the API.

card resource xml - attributes
  • name: String.
  • description: String.
  • card type: Resource; name of the card type for each card; string.
  • id: system assigned unique identifier for a card; Integer, read only.
  • number: unique identifier of a card within a project - Use this for both GET and PUT; integer, read only.
  • project: Resource; name and identifier of a project a card belongs to; both strings.
  • version: current card version. You can specify the version to get history version of the card; integer, read only.
  • project_card_rank: the rank of the card in a project; Integer, read only.
  • created_on: date and time of creating card; Date Time, read only.
  • modified_on: date and time of last modification; Date Time, read only.
  • modified_by: Resource; name and login id of user who is the last to modify the card; both String, read only.
  • created_by: Resource; name and login id of user who created the card; both String, read only.
  • properties: property: Resource; name and a current value for each card property defined for current card's card type are listed; Data type will depend on the property while property name is always String. The property also includes attributes about the property type_description and whether or not it is hidden.

Locating a card

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/cards/card_number.xml
    Parameters: NA

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards/42.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of api/v2/projects/test_project/cards/42.xml represents the card resource for the card numbered 42 in project with identifier test_project.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following. 
<?xml version="1.0" encoding="UTF-8"?>
<card>
  <name>As an API user, I would like to lookup a card in Mingle, given that I know the card number.</name>
  <description>
  </description>
  <card_type>
    <name>Story</name>
  </card_type>
  <id type="integer">409</id>
  <number type="integer">42</number>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
  <version type="integer">1</version>
  <project_card_rank type="integer">1</project_card_rank>
  <created_on type="datetime">2009-10-14T09:14:54Z</created_on>
  <modified_on type="datetime">2009-10-14T09:14:54Z</modified_on>
  <modified_by url="http://localhost:8080/api/v2/users/1.xml">
    <name>anne</name>
    <login>anne</login>
  </modified_by>
  <created_by url="http://localhost:8080/api/v2/users/2.xml">
    <name>jane</name>
    <login>jane</login>
  </created_by>
  <properties type="array">
    <property type_description="Managed text list" hidden="false">
      <name>Status</name>
      <value>Closed</value>
    </property>
    <property type_description="Managed number list" hidden="false">
      <name>Estimate</name>
      <value>4</value>
    </property>
    <property type_description="Managed text list" hidden="false">
      <name>Priority</name>
      <value nil="true"/>
    </property>
  </properties>
</card>

Update a card by the card number

You can update different attributes on a card such as card name, card type or properties that are available on card via card resource API.

How to update different kinds of properties
  • Managed/Unmanaged text: Use the text value of the value you would like to update the value to
  • Managed/Unmanaged numbers: Use the numeric value you would like to set the property to
  • Date: Use the date string in the project date format
  • Team member: Use the id of the user you would like to update the value to. You can obtain the user id by looking up the user using the API.
  • Card: Use the card number of the card you would like to update the value to.

Reference

    Request Method: PUT
    URL: /api/v2/projects/project_identifier/cards/card_number.xml
    Parameters: all card attributes that can be updated

    card[name] : The card name
    card[card_type_name] : The name of the card type
    card[properties][][name] : The name of a property you want to set
    card[properties][][value] : The value of the property named above

Example

    PUT
      
    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards/42.xml
      
    card[name]=new name
    card[card_type_name]=story
    card[properties][][name]=status
    card[properties][][value]=open

Explanation

The above is an example of a PUT request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of api/v2/projects/test_project/cards/42.xml represents the card resource for the card with a card number of 42 in project with identifier test_project. Please note that this is not the card id. The value of the name and card_type_name attributes will get changed to the newly specified values of "new name" and "story" and the a card property called "status" will get a new value of "open".

Please keep in mind that this URL uses the card number, not the card id. The card id is no longer used to identify a card with the latest version of the API (v2) in Mingle 3.0. So please ensure you specify the correct card number, otherwise you may unintentionally update the wrong card and damage your data.

If you are a Mingle or a project admin, you can update hidden properties as well.

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned a location attribute in the http header of the response, which is a URL to the updated resource.

Create a card

Reference

    Request Method: POST
    URL: /api/v2/projects/project_identifier/cards.xml
    Parameters: all card attributes that can be updated

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards.xml

    card[name]=testing card creation
    card[card_type_name]=story

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. Upon execution of this request, the post parameters will be used to create a card on the project with identifier "test_project". The value of the name and card_type_name attributes will be set to the specified values of "testing card creation" and "story".

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned a location attribute in the http header of the response, which is a url from which you can get the card resource that was created.

Get a set of cards for a project

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/cards.xml
    Parameters: 

    view : The name of a saved view, whose cards are to be returned back
    page : A specific set of 25 results, if the list contains more than 25 results. The first 25 results are page 1. The next 25 are page 2, and so on. Requesting the contents of a page of data that is past the last valid page, returns the data on the last valid page and not an empty array.
    filters[] : Each value for this parameter represents a filter applied to the list of cards  
    sort : The property whose value will be used to sort the cards returned
    order : ASC/DESC, whether the cards will be returned in Ascending or Descending order of the sort property 
    tagged_with : A comma separated list of tags that will be used to further filter the list of cards in addition to the filters

Example 1

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards.xml

    filters[]=[Type][is][story]
    filters[]=[Status][is not][accepted]
    sort=status
    order=ASC

Explanation

The above is an example of a GET request to retrieve a filtered set of cards from the project with identifier "test_project". The cards returned will all be of type "Story" and will have a status other than "accepted". They will be returned in the ascending order of their status values, as configured on the property management page in Mingle.

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned an array of card resources. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

<cards type="array">
  <?xml version="1.0" encoding="UTF-8"?>
  <cards type="array">
    <card>
      <name>Automatically update event status when event date has passed</name>
      <description>
      </description>
      <card_type>
        <name>Story</name>
      </card_type>
      <id type="integer">419</id>
      <number type="integer">11</number>
    ...
      <properties type="array">
        <property type_description="Managed text list" hidden="false">
          <name>Status</name>
          <value>New</value>
        </property>
      ...
      </properties>
    </card>
    <card>
      <name>Add details to event</name>
      <description>
      </description>
      <card_type>
        <name>Story</name>
      </card_type>
      <id type="integer">424</id>
      <number type="integer">16</number>
    ...
      <properties type="array">
        <property type_description="Managed text list" hidden="false">
          <name>Status</name>
          <value>Open</value>
        </property>
      ...
      </properties>
    </card>

Example 2

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards.xml

    view=Open Stories

Explanation

The above is an example of a GET request to retrieve all cards in the saved view called "Open Stories" in the project with identifier "test_project".

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned an array of card resources, in which each card resource would be a card in the "Open Stories" view. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

<cards type="array">
  <card>
    <name>Show event details in event list</name>
    <description>
    </description>
    <card_type>
      <name>Story</name>
    </card_type>
    <id type="integer">410</id>
    <number type="integer">2</number>
  ...
    <properties type="array">
      <property type_description="Managed text list" hidden="false">
        <name>Status</name>
        <value>Open</value>
      </property>
    ...
    </properties>
  </card>
  <card>
    <name>Create event and view event in an event list</name>
    <description>
    </description>
    <card_type>
      <name>Story</name>
    </card_type>
    <id type="integer">409</id>
    <number type="integer">1</number>
  ...
    <properties type="array">
      <property type_description="Managed text list" hidden="false">
        <name>Status</name>
        <value>Open</value>
      </property>
    ...
    </properties>
  </card>
</cards>

Get all cards that belong to a tree

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/cards.xml
    Parameters:

    tree_name: The name of a tree, whose cards are to be returned back

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards.xml

    tree_name=Planning Tree

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. This request will return all cards that belong to a 'Planning Tree'.

Result

If you have sufficient permissions to perform the action and the action was successful, you will be returned an array of card resources. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

<cards type="array">
  <card>
    <name>Story 1</name>
    <description nil="true"></description>
    <card_type>
      <name>Story</name>
    </card_type>
    <id type="integer">431</id>
    <number type="integer">4</number>
  ...
    <properties type="array">
      <property type_description="Any card used in tree" hidden="false">
        <name>Release</name>
        <value url="http://localhost:8080/api/v2/projects/test_project/cards/1.xml">
          <number type="integer">1</number>
        </value>
      </property>
      <property type_description="Any card used in tree" hidden="false">
        <name>Iteration</name>
        <value nil="true"></value>
      </property>
    </properties>
  </card>
  <card>
    <name>Iteration 1</name>
    <description nil="true"></description>
    <card_type>
      <name>Iteration</name>
    </card_type>
    <id type="integer">430</id>
    <number type="integer">3</number>
  ...
    <properties type="array">
      <property type_description="Any card used in tree" hidden="false">
        <name>Release</name>
        <value url="http://localhost:8080/api/v2/projects/test_project/cards/1.xml">
          <number type="integer">1</number>
        </value>
      </property>
    </properties>
  </card>
  <card>
    <name>Release 1</name>
    <description nil="true"></description>
    <card_type>
      <name>Release</name>
    </card_type>
    <id type="integer">428</id>
    <number type="integer">1</number>
  ...
    <properties type="array">
    </properties>
  </card>
</cards>

Get a set of cards in a tree

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/cards.xml
    Parameters:

    tree_name: The name of a tree, whose cards are to be returned back
    excluded[]: Any card type that is not wished to be returned back
    tf_card_type[] : A tree filter for the specified card type.
    tagged_with : A comma separated list of tags that will be used to further filter the list of cards in addition to the filters
    all tree properties

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards.xml

    tree_name=Planning Tree
    excluded[]=Defect
    tf_release[]=[Release][is][1]

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. This request will return all cards that belong to the Release card numbered 1 in the 'Planning Tree', while excluding the Defect card types. For example, let's say you have two Defects and one Story that belong to Release card numbered 1. This request will only return one story card since the Defect card type is excluded.

Result

If you have sufficient permissions to perform the action and the action was successful, you will be returned an array of card resources. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

<cards type="array">
  <card>
    <name>Story 1</name>
    <description nil="true"></description>
    <card_type>
      <name>Story</name>
    </card_type>
    <id type="integer">431</id>
    <number type="integer">4</number>
  ...
    <properties type="array">
      <property type_description="Any card used in tree" hidden="false">
        <name>Release</name>
        <value url="http://localhost:8080/api/v2/projects/test_project/cards/1.xml">
          <number type="integer">2</number>
        </value>
      </property>
      <property type_description="Any card used in tree" hidden="false">
        <name>Iteration</name>
        <value nil="true"></value>
      </property>
    </properties>
  </card>
  <card>
    <name>Iteration 1</name>
    <description nil="true"></description>
    <card_type>
      <name>Iteration</name>
    </card_type>
    <id type="integer">430</id>
    <number type="integer">3</number>
  ...
    <properties type="array">
      <property type_description="Any card used in tree" hidden="false">
        <name>Release</name>
        <value url="http://localhost:8080/api/v2/projects/test_project/cards/1.xml">
          <number type="integer">2</number>
        </value>
      </property>
    </properties>
  </card>
  <card>
    <name>Release 1</name>
    <description nil="true"></description>
    <card_type>
      <name>Release</name>
    </card_type>
    <id type="integer">428</id>
    <number type="integer">1</number>
  ...
    <properties type="array">
    </properties>
  </card>
</cards>

Get all cards for a project

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/cards.xml?page=all

Example 1

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards.xml?page=all

Explanation

The above is an example of a GET request to retrieve all cards from the project with identifier "test_project". This will return all cards for the project.

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned an array of card resources. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

  <cards type="array">
    <card>
      <name>Story</name>
      <description nil="true"></description>
      <card_type>
        <name>Story</name>
      </card_type>
      <id type="integer">437</id>
      <number type="integer">10</number>
     ...
    </card>
    .
    .
    .
    <card>
      <name>Release 1</name>
      <description nil="true"></description>
      <card_type>
        <name>Release</name>
      </card_type>
      <id type="integer">428</id>
      <number type="integer">1</number>
    ...
    </card>
  </cards>