Help

Card API

Cards

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

Please keep in mind that in many other parts of the system, the system assigned identifier, id, is used to identify a card. If you do not specify the correct card id, you may end up updating the wrong card, and damage your data.

Before you manipulate cards using the API, we recommend that familiarize yourself with some key concepts dealing with cards like card types, and card properties.

Click here to learn more about card types.

Click here to learn more about card properties.

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_at etc., are provided only as information about the card and cannot be updated through the API.

card resource xml - attributes
  • card_type_name: String; the name of the card type existing in the project
  • comment: String; only returned in the history version of the card, read only. You cannot specify a comment on create/update of a card.
  • cp_column_name an attribute for each card property defined for that card type e.g. cp_story_status. Data type will depend on the property.
  • created_at: Date Time; date and time of creating card, read only.
  • created_by_user_id: Integer; the id of user who created this card, read only.
  • description: String;
  • id: Integer; read only, system assigned unique identifier for a card - do not use this in GET, use number instead.
  • modified_by_user_id: Integer; the id of user who is the last one modified the card, read only.
  • name: String;
  • number: Integer; unique identifier of a card within a project.
  • project_id: Integer; the id of project having this card, read only.
  • updated_at: Date Time; date and time of last modification, read only.
  • version: Integer; card version, read only. You can specify the version to get history version of the card.

Locating a card

Reference

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

Example

        GET
      
        http://yourname:password@your.mingle.server:8080/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, post 8080. The request is made with the authorization credentials of yourname/password. The URL of 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 a xml document that looks something like the following. 
<?xml version="1.0" encoding="UTF-8"?>
<card>
  <card_type_name>story</card_type_name>
  <cp_feature>api</cp_feature>
  <cp_owner_user_id type="integer"></cp_owner_user_id>
  <cp_priority>urgent</cp_priority>
  <cp_release>R1</cp_release>
  <cp_status>Open</cp_status>
  <created_at type="datetime">2006-04-04T04:33:35Z</created_at>
  <created_by_user_id type="integer">31</created_by_user_id>
  <description></description>
  <has_cross_project_macro type="boolean"></has_cross_project_macro>
  <id type="integer">900</id>
  <modified_by_user_id type="integer">31</modified_by_user_id>
  <name>As an API user, I would like to lookup a card in Mingle, given that I know the card number.</name>
  <number type="integer">42</number>
  <project_id type="integer">2</project_id>
  <updated_at type="datetime">2006-04-07T07:28:23Z</updated_at>
  <version type="integer">3</version>
</card>

Update a card by id

Reference

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

Example

        PUT
      
        http://yourname:password@your.mingle.server:8080/projects/test_project/cards/2668.xml
      
        card[name]=new name
        card[card_type_name]=story

Explanation

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

Please keep in mind that this URL uses the card id, not the card number. If you are not sure what the card id is, use the API to look up the card by number, and extract the value of the id attribute. If you do not specify the correct card id, you may end up updating the wrong card, and damage your data.

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.

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 id of the card you would like to update the value to. You can obtain the card id by looking up the card using the API. Do not use the card number here.

Create a card

Reference

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

Example

        POST
    
        http://yourname:password@your.mingle.server:8080/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, post 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 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: /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/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">
  <card>
    <card_type_name>Story</card_type_name>
    <cp_status>New</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
    .
    .
    .
  <card>
    <card_type_name>Story</card_type_name>
    <cp_status>Open</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
</cards>

Example 2

        GET

        http://yourname:password@your.mingle.server:8080/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>
    <card_type_name>Story</card_type_name>
    <cp_status>Open</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
    .
    .
    .
  <card>
    <card_type_name>Story</card_type_name>
    <cp_status>Open</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
</cards>

Get all cards that belong to a tree

Reference

Request Method: GET
URL: /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/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, post 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>
<card_type_name>Defect</card_type_name>
<cp_card_prop_card_id type="integer" nil="true"></cp_card_prop_card_id>
<cp_defect_status>Fix in progress</cp_defect_status>
<cp_iteration_card_id type="integer">2107</cp_iteration_card_id>
<cp_release_card_id type="integer">2105</cp_release_card_id>
<cp_story_card_id type="integer">2108</cp_story_card_id>
<cp_story_status nil="true"></cp_story_status>                        
...
</card>
<card>
<card_type_name>Story</card_type_name>
<cp_card_prop_card_id type="integer" nil="true"></cp_card_prop_card_id>
<cp_defect_status nil="true"></cp_defect_status>
<cp_iteration_card_id type="integer">2107</cp_iteration_card_id>
<cp_release_card_id type="integer">2105</cp_release_card_id>
<cp_story_card_id type="integer" nil="true"></cp_story_card_id>
<cp_story_status>new</cp_story_status>                          
...
</card>
.
.
.
<card>
<card_type_name>Release</card_type_name>
<cp_card_prop_card_id type="integer" nil="true"></cp_card_prop_card_id>
<cp_defect_status nil="true"></cp_defect_status>
<cp_iteration_card_id type="integer" nil="true"></cp_iteration_card_id>
<cp_release_card_id type="integer" nil="true"></cp_release_card_id>
<cp_story_card_id type="integer" nil="true"></cp_story_card_id>
<cp_story_status nil="true"></cp_story_status>
...
</cards>

Get a set of cards in a tree

Reference

Request Method: GET
URL: /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  
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/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, post 8080. This request will return all cards that are belong to a Release card number 1 'Planning Tree' except all Defect card types. For example, let's say you have two Defects and one Story belong to Release card number 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>
 <card_type_name>Story</card_type_name>
 <cp_card_prop_card_id type="integer" nil="true"></cp_card_prop_card_id>
 <cp_defect_status nil="true"></cp_defect_status>
 <cp_iteration_card_id type="integer">2107</cp_iteration_card_id>
 <cp_release_card_id type="integer">2105</cp_release_card_id>
 <cp_story_card_id type="integer" nil="true"></cp_story_card_id>
 <cp_story_status>new</cp_story_status>
 ...
</card>
 .
 .
 .
<card>
 <card_type_name>Release</card_type_name>
 <cp_card_prop_card_id type="integer" nil="true"></cp_card_prop_card_id>
 <cp_defect_status nil="true"></cp_defect_status>
 <cp_iteration_card_id type="integer" nil="true"></cp_iteration_card_id>
 <cp_release_card_id type="integer" nil="true"></cp_release_card_id>
 <cp_story_card_id type="integer" nil="true"></cp_story_card_id>
 <cp_story_status nil="true"></cp_story_status>
</cards>
</cards>

Get all cards for a project

Reference

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

Example 1

          GET

          http://yourname:password@your.mingle.server:8080/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>
      <card_type_name>Story</card_type_name>
      <cp_status>New</cp_status>
      <cp_group>Profile Module</cp_group>
      ...
    </card>
      .
      .
      .
    <card>
      <card_type_name>Story</card_type_name>
      <cp_status>Open</cp_status>
      <cp_group>Profile Module</cp_group>
      ...
    </card>
  </cards>