Skip to main content
System StatusContact Support Agility Community

Exercise 6: Update your Story


This tutorial will help you query the Story created in Exercise 4 using the Rest API.


  • Knowledge of the VersionOne API Console

  • Basic Knowledge of XML

What you'll learn

This exercise walks you through the process of changing data in the Reference attribute, deleting an Owner, and adding a new Owner.

Step 1: Recall the OID of the newly created story

Recall the saved OID Story:1045 returned in the response from the output in Exercise 4: Create your own Story (Backlog Item) within a Scope and Exercise 5: Query your Story.

Step 2: Select attributes to update, build a payload, and execute POST

Recall from Exercise 3: Query a Scope (Project) for Specific Attribute, the metadata query.  For this exercise, we will update the Owners and Reference attributes. To find the OIDs for the Owners relation, recall Exercise 3: Query a Scope (Project) for Specific Attribute, Step 3, Methods 1 and 2.  

Select the scope that will be the destination for your new story. For our example, we are going to add to the Scope called "VersionOne Rest APIs 101".

There are two ways to find the OID of the project that you are interested in using to hold your new story. You can find the project OID from the Lifecyle UI or you can query the project from the API.  Both methods are described here.

Method #1 - Query for a Member using the VersionOne UI

Under ADMIN/Members/Members, you will see a list of the members in VersionOne.  If you hover over the member's name, you will see the OID for that member in the status at the bottom, left side of the page. In the case of Billy Agile, his OID is Member:1043

Method #2 - Query for a destination project using the VersionOne Rest API 

Run this query: rest-1.v1/Data/Member?sel=ID&where=Name='Billy Agile'.

Here is the response. Confirm that the OID from this response matches the OID discovered in the UI.

Now that we have established what the Member OIDS were, we can build the payload.

<Attribute name="Reference" act="set">MyNewReference-123</Attribute>
<Relation name="Owners" >
    <Asset idref="Member:20" act="remove" />
    <Asset idref="Member:1043" act="add"/>


  1. Select the GET drop and change it to POST then observe the editor at the bottom.

  2. Construct your payload.

  3. Enter the above payload into the editor and change the URL so it looks like this:

    Enter this into the URL box rest-1.v1/Data/Story/1045 and click Send.

Step 3: Examine response

Observe a similar results to the output below.

Notice here we have Story:1045:1160.  Consistent with my previous mention of moments, a new moment is generated from this update to our story. If you examine the output below you will see that it shows the Reference and Owners attributes with new content. 

Step 4: Examine the newly modified attributes

  • Change your POST button back to GET.

  • Modify the URL to be rest-1.v1/Data/Story/1045?sel=Reference,Owners and click Send.

This confirms that our simultaneous changes to an asset was successful.


  • Queried the contents of a project using an OID.

  • Perform simultaneous changes to attributes on a single story.


What two ways to find the Scope's OID did we explore?

Query in VersionOne UI
Query via Query.v1 endpoint
Query via Rest-1.v1