Skip to main content
System StatusContact Support Agility Community

Bulk API Quick Start

This endpoint was introduced in 18.0, Winter 2018. Please view the About VersionOne information from the orange help icon in the menu bar to see if you are on this release or later.


The VersionOne Bulk API provides a rich set of bulk operations against your VersionOne instance.  This enables you to:

•    Create/Delete large amounts of data without iterating through OIDS
•    Create/Delete large amounts of data given complex filtering criteria 


To use the Bulk API, any rest client will do.  For this quickstart, you can use any rest client to test out the samples.



If you are not familiar with using VersionOne APIs and related terminology, please visit the VersionOn Lifecyle Rest API Tutorial prior to attempting to work with this quickstart. 



When using any of the VersionOne API, you will have to authenticate.  Authentication comes in two flavors

1.  Basic Authentication
2.  Access Token Authentication

If you are doing "one-offs" in some browser based Rest tool and you are logged into VersionOne on a different tab, you are already authenticated and can do operations against your VersionOne instance.  If you are not, you will have to use Access Token Authentication to perform any bulk operations.  Please examine the documentation for Access Token Authentication if you have questions.

Basic Concepts of usage

There are essential 3 parts that are necessary for using the Bulk API

1. URL  - This is the endpoint that you are going to POST to.  The Bulk API endpoint URL is in the format listed below. Note: "previewOnly=true" can be omitted if you are confident with the payload being sent to the endpoint.


2. Preview Mode - Include "previewOnly=true" in URL query parameters

We recommend executing commands in preview mode by including the query parameter "previewOnly=true" before executing commands in commit mode ("previewOnly=true" omitted). This will allow you to explore the usage/syntax of the API safely. The response from the endpoint will include the set of assets that would have be modified if the command had been executing in commit mode.

3. Headers - The two headers that must be set are

Authorization: Bearer 1.jnzHS3VHv80DE/coUak6OcXBvGQ=
Content-Type: application/json

4. Payload - While there are some variation of complexity in the types of payloads, it is a json object and the simplest form to create an asset follows this basic format

  "AssetType" : "Story",
  "Name" : "Fuzzy Story",
  "Scope" : "Scope:12345"

This payload creates a single new Story asset inside of a Scope (project) with the OID of Scope:12345.

As with any VersionOne APIs, the default attributes are dictated by the metadata associated with the particular asset that you are creating.  For example if you are creating a Story, a Story has to have at minimal, the following attributes
Name : Text
Scope : Relation to a scope


These are defined as system defaults by VersionOne business rules.  In addition to these required attributes, your VersionOne administrator can decide that in order to create a Story, some other attribute can be required to have a value when creating a new Story asset.  Before you decide to create an asset, take a look at the corresponding metadata.

Creating multiple objects is what make the Bulk API special so here is an expansion of the previous payload to illustrate the creation of multiple assets.

   "AssetType" : "Story",
   "Name" : "Fuzzy Story",
   "Scope" : "Scope:12345"
   "AssetType" : "Defect",
   "Name" : "Fuzzy Defect",
   "Scope" : "Scope:12345"

Here are some interesting things about...