API Versioning

Service versioning

CA Agile Central's Web Services API supports versioning. Attributes and objects are routinely added and occasionally modified. When these changes break backwards compatibility, the API version number is incremented.

Most recent version: v2.0

Currently supported versions: 1.08, 1.09, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16, 1.17, 1.18, 1.19, 1.20, 1.21, 1.22, 1.23, 1.24, 1.25, 1.26, 1.27, 1.28, 1.29, 1.30, 1.31, 1.32, 1.33, 1.34, 1.35, 1.36, 1.37, 1.38, 1.39, 1.40, 1.41, 1.42, 1.43, v2.0

The version number is included in the URL used for API calls. This includes the ref URLs for all objects in the system.

For instance, a defect with ObjectID 123 will have the following URLs for different versions of the API:

  • https://rally1.rallydev.com/slm/webservice/1.08/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.09/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.10/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.11/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.12/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.13/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.14/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.15/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.16/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.17/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.18/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.19/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.20/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.21/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.22/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.23/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.24/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.25/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.26/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.27/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.28/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.29/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.30/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.31/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.32/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.33/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.34/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.35/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.36/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.37/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.38/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.39/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.40/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.41/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.42/defect/123
  • https://rally1.rallydev.com/slm/webservice/1.43/defect/123
  • https://rally1.rallydev.com/slm/webservice/v2.0/defect/123
  • https://rally1.rallydev.com/slm/webservice/v3.0/defect/123

Changes in API version 1.08

  • Moved EmailAddress from UserProfile to User
  • Added Disabled to User
  • Added Children to TestFolder
  • Added Parent to TestFolder
  • Added Url to WebLinkDefinition

Changes in API version 1.09

Added Modules to Subscription.

Changes in API version 1.10

  • TestSet has been introduced
  • Added FormattedID to TestFolder
  • Added batch query support (Refer to the Batch Query section for full documentation)
  • Enhanced fetch parameter for REST queries to allow specifying a comma-separated list of (case-insensitive) attribute names; only the attributes specified will be returned in the query results
    • Note: Whitespace is not allowed between commas and attribute names

Changes in API version 1.11

  • Required now displays in the Type Definition for each attribute as either true or false
  • Added TestSet to TestCaseResult
  • Deleting a HierarchicalRequirement, TestCase, Defect, or Task through web services will move the object to the recycle bin for a User Story subscription
    • Use Case mode subscriptions will continue to delete all objects
    • This affects all previous versions of web services

Changes in API version 1.12

Program has been introduced.

Changes in API version 1.13

  • Tag has been introduced
  • tags attribute on Artifact has been introduced
  • Predecessors and Successors on Hierarchical Requirement no longer point to the abstract Requirement

Changes in API version 1.14

role attribute on User has been introduced.

Changes in API version 1.15

  • TimeEntryItem has been introduced
  • TimeEntryValue has been introduced
  • Added DisplayName to TypeDefinition

Changes in API version 1.16

  • ArtifactNotification has been introduced
  • Added load to UserIterationCapacity
  • Added taskEstimates to UserIterationCapacity
  • Added timeTrackerEnabled to WorkspaceConfiguration

Changes in API version 1.17

Changed duration for TestCaseResult from xsd:long to xsd:double.

Changes in API version 1.18

  • Changed contains query arguments to not be case sensitive
  • Changed owner for Artifact from xsd:string to User
  • Added user to ArtifactNotification
  • Removed userName from ArtifactNotification
  • Changed user for Attachment from xsd:string to User
  • Changed blockedBy for Blocker from xsd:string to User
  • Added user to ConversationPost
  • Removed userName from ConversationPost
  • Changed submittedBy for Defect from xsd:string to User
  • Changed owner for Program from xsd:string to User
  • Changed owner for Project from xsd:string to User
  • Changed user for Revision from xsd:string to User
  • Changed tester for TestCaseResult from xsd:string to User
  • Changed user for TimeEntryItem from xsd:string to User
  • Added user to UserIterationCapacity
  • Removed userName from UserIterationCapacity
  • Changed owner for Workspace from xsd:string to User
  • Deprecated current pointer, it remains pointed at version 1.17 and will continue to point there until its removed

Changes in API version 1.19

Changed rank for HierarchicalRequirement, Defect, DefectSuite, Task, TestSet from xsd:double to xsd:decimal.

Changes in API version 1.20

  • Changed the name of the collection of Projects on User from projects to teamMemberships
  • Changed the name of the collection of Users on Project from users to teamMembers

Changes in API version 1.21

  • Changeset has been introduced
  • Change has been introduced
  • SCMRepository has been introduced
  • Added uri to BuildDefinition
  • Changed the name of state to lastStatus on BuildDefinition
  • Added uri to Build
  • Added start to Build
  • Added changesets to Build
  • Changed the name of label to number on Build
  • Added changesets to Defect, Task, HierarchicalRequirement
  • Added taskStatus to HierarchicalRequirement, Defect, DefectSuite

Changes in API version 1.22

  • Added defectStatus to HierarchicalRequirement, DefectSuite, TestCase
  • Added testCaseStatus to HierarchicalRequirement, Defect, TestSet
  • Changed project for Task to be read-only
  • Added archived to Tag
  • Added name to Changeset
  • SCMRepository objects may now be associated with multiple projects
    • Added a read-only collection of Projects to SCMRepository
  • BuildDefinition objects may now be associated with multiple projects
    • Added a read-only collection of Projects to BuildDefinition
  • Added lastBuild to BuildDefinition
  • Uri is no longer mandatory for SCMRepository, Changeset, and Change
  • Message is no longer mandatory for Changeset
  • CommitTimestamp is now mandatory for Changeset
  • Artifacts may now be used in queries on Changesets
  • Base now has a maximum length of 4000 on Change
  • Extension now has a maximum length of 4000 on Change

Changes in API version 1.23

  • Preference has been introduced
  • Added onpremLdapUsername to User

Changes in API version 1.24

Supporting version 1.24 of the AppSDK.

Changes in API version 1.25

Support attribute inheritance from all parents for a given type definition.

Changes in API version 1.26

Added tasks attribute (collection of Task objects) to TestSet.

Changes in API version 1.27

No visible changes.

Changes in API version 1.28

Added inProgressDate attribute to HierarchicalRequirement, Defect, and Defect Suite. This is a read-only attribute that is tied to the In-Progress schedule state. When the schedule state of one of these entities goes from less than In-Progress to In-Progress or greater, the In-Progress Date is set. If the schedule state goes to something less than In-Progress, then the date is set null (empty). Accepted Date has been changed to follow this convention as well.

Changes in API version 1.29

Attachments and Attachment Content are now creatable objects through web services. You can also associate the attachment to an artifact from the attachment end point.

Changes in API version 1.30

Some date attributes represent the start of the day or end of the day in the workspace's time zone. When updating data or making queries against these attributes, the time portion of the date is ignored. The specified date will either be adjusted to the start or the end of the day in the workspace's time zone, ensuring that the date falls on the same day as the specified date in the time zone offset provided. If no time zone offset is provided, the offset for the user's time zone is used. If the user's time zone is not set, the workspace's time zone will be used.

  • The workspace's time zone is America/Los_Angeles (with an offset of -0800).
  • The user is working in the America/New_York time zone (with an offset of -0500).
  • The user creates an iteration with a start date of 2012-02-18T00:00:00:000-0500.
  • The start date is adjusted to 2012-02-18T03:00:00:000-0500 (based on the start of the day in the workspace's time zone).
    • Note that while the time was adjusted the result is on the same day in the user specified offset.
  • The start date, as returned by the API, rendered in UTC: 2012-02-18T08:00:00:000Z.
  • The following attributes are adjusted to the start of the day (00:00:00) in the workspace's time zone:
    • Defect.TargetDate
    • Iteration.StartDate
    • Release.ReleaseStartDate
  • The following attributes are adjusted to the end of the day (23:59:59) in the workspace's time zone:
    • Iteration.EndDate
    • Release.ReleaseDate
  • When passing dates through the API, you must use an ISO 8601 date with an optional offset (such as 2015-09-21T15:10:09:000-0600).

Changes in API version 1.31

  • Attachments are now queryable
  • Conversation Posts can now be edited by the creator and deleted by the creator or an administrator

Changes in API version 1.32

Exposed DragDropRankingEnabled attribute on WorkspaceConfiguration. This is a read-only attribute that indicates whether the workspace supports drag-and-drop ranking. This attribute is changeable in the workspace editor.

Changes in API version 1.33

Exposed appId attribute on Preference.

Changes in API version 1.34

Added Test Case Result attribute to Attachment so Test Case Results can be attached.

Changes in API version 1.35

  • Added Story Hierarchy Enabled, Maximum Projects, Subscription Type, Project Hierarchy Enabled, and Expiration Date attribute to Subscription.
  • Added Landing Page attribute to User.

Changes in API version 1.36

Added Subscription Admin attribute to User.

Changes in API version 1.37

  • Expose Creatable, IDPrefix, Ordinal, Restorable, RevisionHistory, and TypePath attributes on Type Definition
  • Portfolio Item has been introduced
  • Can now create instances of Type Definition with Portfolio Item parent
  • Preliminary Estimate has been introduced
  • State has been introduced
  • Added Editors attribute to Project

Changes in API version 1.38

  • Added HasParent attribute to User Story
  • Added Ready attribute on Artifact
  • Added BlockedReason attribute on Defect, DefectSuite, HierarchicalRequirement, Task and TestSet

Changes in API version 1.39

Added DirectChildrenCount attribute to User Story.

Changes in API version 1.40

  • Added Requirement to Defect in Community Edition
  • Added Defects and DefectStatus to User Story in Community Edition
  • Renamed Resources on Release and Iteration to PlannedVelocity
  • Exposed RevisionHistory attribute on Revision
  • Added StoryHierarchyType attribute to Subscription
  • Added summarization options for Artifact collections

Changes in API version 1.41

  • Added Rank to Test Case
  • Added CostCenter to User
  • Added NetworkID to User
  • Added OfficeLocation to User
  • Added Phone to User
  • Added Role to User
  • Added Department to User
  • Custom fields on User are now queryable

Changes in API version 1.42

Added LastLoginDate to User.

Changes in API version 1.43

  • Added Feature to User Story
  • Added Display Color to Artifact

Changes in API version v2.0

  • Removed the SOAP API and all associated documentation including the WSDL
  • The REST API only supports JSON. XML is no longer supported. The XML schema has been removed
  • c_ is pre-pended to custom field names
  • An object that has child collections, such as a user story that has child user stories or defects, contains a reference to the child collection; the collection of child objects can be accessed directly with the children endpoint
    • For example:
      • User Stories - https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/‹ObjectID›/children
      • Defects - https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/‹ObjectID›/defects
  • ObjectIDs have been changed from a Long Integer type to a String
  • Added Latest Discussion Age In Minutes to Artifact
  • Added Task Status to Test Set
  • Added Expedite to Artifact

Changes in API version v3.0 (beta)

The ObjectID uses a UUID format, which is different than the ObjectID format used in the 1.x and v2.x API versions. The old ObjectID format may still be used in queries in the v3.x API versions; however, only UUID-format ObjectIDs will be returned.


Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.