ALM How to Get Started Using the ALM REST API

ALM How to Get Started Using the ALM REST API


With the release of ALM 11, HP now offers an API that allows the user to interact with QC/ALM using REST. Rather than writing OTA code, one can now accomplish some of the same functionality using a browser as a client – no code writing needed.

Of course, you can also use tools like soapUI to work with ALM or create custom applications using languages like VBscript, C# and Java that interact with ALM.

But to keep it simple, we’ll start by taking a look at how to get started using your browser as a client.

Getting started using your browser as a client

The first thing you’ll need to do before using the ALM REST API is to authenticate your user. You can do this by obtaining a session cookie which returns a token that, by default, times out after one hour of inactivity.

Authenticate your user

1. Determine whether your user is currently authenticated by navigating to:


If your user is not currently authenticated, you’ll get an HTTP Status Code 401.

2. To authenticate your user, navigate to:


3. Enter the ALM login name and password you want to authenticate:


4. If your ALM user is authenticated, you’ll get the following XML:


How to READ an ALM defect

You should now be authenticated. Cool! Next, let’s make sure we’re able to retrieve the very first defect in ALM.


1. To READ an ALM defect record, place the following URL (using your ALM instance info) into your browser:




2. The first defect should populate your browser with its XML info:



Although our example returned info for a defect in ALM, you can also read info for the other ALM entities, which are:


  • Defects
  • Resources
  • Requirements
  • Tests
  • Test lab

For example – if we wanted to read the first requirement info from ALM, we would simply change the defect URL we used to point to requirements instead of defects:



Other common tasks you can perform

We saw in the example above how easy it is to READ an existing record in ALM. Some other common tasks that can be performed using the ALM API are:


  • Create
  • Delete
  • Read
  • Update

That should be enough info to get you started using the ALM REST API. For more info, be sure to check out HP’s ALM REST API doc – and as always, drop me a line with any questions or comments!

Ganesh - April 13, 2013

Hi Joe,

I would like to understand how do I perform database queries using REST API. Similar to using the tdconnectin.command object, used to query multiple tables, is there a way to accomplish this using REST?


Harpreet - May 9, 2013


I am trying to access the rest api via python. However, I seem to be unable to authenticate. Would you have any sample python code that I can use as an example?

    Joe Colantonio - May 21, 2013

    Does anyone have any example using Python that they could share with us?

selva - May 14, 2013

Good Article!!

prateek - May 24, 2013

Hi Joe,

Using rest it is possible to get the test script of a test.

/tests/{TestID}/storage/{File path}

What does “{File path}” means over here.

Vineet - May 28, 2013

Hi Joe,

Is there any reference document for REST APIs for ALM>


Mohana Priya - June 4, 2013

How to delete, update a defect in QC by using REST API ( in browser).

priya - June 6, 2013

Hi Joe,
As mentioned in the topic “ALM 11 – GETTING STARED WITH REST API ” , about reading a defect. I need a detailed steps for deleting and updating a defect or any entity. can any one help me in this?

Jayashree - June 13, 2013

Hi Joe,

I am trying to access the URL with our ALM path, however i am seeing the error “The requested resource (/qcbin/rest/is-authenticated) is not available”. Please help me with this. Thanks!

Jayashree SN

Josh Stein - September 9, 2013


Thanks for the examples. It definitely helped me get started. However, your defect example has the wrong format. The screenshot is fine, but I think you updated the wrong values in the text. The format should be this:


    Joe Colantonio - September 9, 2013

    Thanks Josh for letting me know about this. It should now be in the correct format. Thanks!!!

Atul Pandey - September 28, 2013

Hi Joe,

Great site and good articles. I am using QC 11.52 and trying to write a VAPI-XP automated test case using perl script and calling a java program through it. I am using the VAPI test wizard but it asks me to download BSF (Bean Scripting Framwork). I have already downloaded it but still it and placed the path in the classpath of environment variable but still it gives me the same JVM not founf error. Can you please let me know if it is even possible to do what I am doing and if yes what am I missing.

Require your immediate help.


    Joe Colantonio - October 5, 2013

    Hi Atul I have not seen this issue. If you go to a command prompt and type java -version does it find the java version info? If not then it is definitely a path issue not being properly defined in you environment variables. What is throwing the JVM not found error ALM?

Ivan - October 17, 2013

Nice post.

Do you have any examples on how to post(create) or delete a defect or any other entity?


    Joe Colantonio - October 19, 2013

    Thanks Ivan – I will try to create an example soon and post it.

Sriram - December 10, 2013

Hi Joe,
Thanks for this wonderful Post.I need a solution for this.
I need to pull defects that are not linked to any Test cases alone using Rest API.I tried several ways like, 1.Putting cross filter with Defects and Test Set
2. http://ALM SERVER/qcbin/rest/domains/xxx/projects/YYY/defects/1/defect-links.This seems to work for only 1 defect.How can I retrieve the same info for a group of defects?
CAn any one help me plz

    Joe Colantonio - December 11, 2013

    I’ve been meaning to write another post on this but have not had time – you could do this programmatically using a cool ALM REST API wrapper I recently found at

      BVR - April 3, 2015

      Hi Joe,

      Thanks for your wonderful post.

      By following your examples, I am able authenticate and get the defect information in xml format, but my requirement is to access a defect directly from a URL in HPALM itself.

      Can you please suggest a way?

      Appreciate your help with this.

      Thanks & Regards,

Sriram - December 12, 2013

Thanks Joe,Could you please let us know the Website or blog where you found it.(ALM REST API Wrapper)

    Joe Colantonio - December 12, 2013

    Sorry forgot to add it :) –>

      Sriram - December 30, 2013

      Hi joe.I need Defect lists that are not linked to any test cases alone.I do not have much knowledge in JAVA.But I use Parasoft tool so I need to code in Java only.Could anyone please help me in this?

      Chris Nippard - March 23, 2015

      The link you have provided on this page is dead… Is there an update? Thanks!

        Joe Colantonio - March 31, 2015

        Hi Chris – which link does not work for you? I think I tried all of them without issues. Thanks!

Abhinandan - December 17, 2013

Thanks joe, your document helped me to achieve my first step of authenticating with ALM 11.0, i was struggling for such a document for almost 3 weeks.
I need your help in the below query. I authenticated successfully but later when i used the below query to GET data it was saying unauthorized. Can you please help me why was it saying unauthorized here.

    Joe Colantonio - December 21, 2013

    Did you start getting the unauthorized message right away? I think it times out after 30 minutes and you need to reauthorized again.

Swatp - January 8, 2014

Please guide me the details step to configure soapui 4.6 with ALM 11 ??

For example how to do a Post/Get request for defect entity, i am getting authentication error as “HTTP Status 401 – An Authentication object was not found in the SecurityContext” even though i am passing all the authentication parameters with the soap request.

Robert - January 28, 2014

I’m having trouble with the API. I can insert a valid defect fine, but the problem arises when I try to insert a defect with a problem, like for example the data I am trying to insert is longer than the ALM field can handle. Instead of rejecting the input, the API allows the attempt, then creates an empty defect with only the Defect ID. Obviously I will try not to insert invalid data, but you never know if a field will be changed or deleted on the ALM side. Is there some way to tell ALM to reject my API input instead of creating an empty defect?

Vivek - February 10, 2014

Getting a some info with Rest will be easy way…

Ibrahimsha - March 25, 2014


Please help!!!!!

Am working on this REST API. I have a problem now and need to know whether it is possible to read tables using REST API.
I have a table “common_settings” related to a project, it contains all the settings related to that project.

Thanks in advance.

Pratik - April 16, 2014

Hi Joe,
Can we login to http://yourALMServer/qcbin/rest/is-authenticated?login-form-required=y URL with the help of REST? Do we have any option to do this? Please help for this.

Pratik - May 6, 2014

Hi Dear Friend,
To login in HP/ALM using REST, I am using following code.
Response response=given().that().parameter(“j_username”,userName).parameter(“j_password”, password).when().get(“http://x-xxxx.YY:YYYY/qcbin/rest/is-authenticated?login-form-required=y”).then().extract().response();
But i am not able to. I am getting login page as reponse and not XML that you told. If i logged in manually, I am getting XML. Please help me out asap, others too who all are visitng this page.
Thanks in advance.

Steven - May 8, 2014

I have found that your comments where the most helpful if any thing that I have found on this subject.

I have a question. When I connect through the browser and run the following query and get a single response.
but when I do the same thing through my java app it return the complete collection.

Any ideas?

    ayush - January 12, 2015

    im having the exact same issue, do u have a solution yet??

Mark Stevens - September 10, 2014

Hi Joe,

It looks like the location for that HP ALM Rest Wrapper has been moved as it now comes upwith not found on codeplex. Do you have a copy or know the location for the new site?

    Joe Colantonio - September 16, 2014

    Hi Mark – sorry I don’t know – I can’t find it either now. let me see if I have it on any of my local machines, if i do I will place it in my downloads sections.

Sovanlal Guchhait - September 25, 2014

When I am using http://yourALMServer/qcbin/rest/is-authenticated in my browser instead of 401 I am getting 404 error. Is it not applicable for hp QC ver10. I am not posting server name and port number for security reason. Could you please help on this

    Joe Colantonio - September 26, 2014

    Hi Sovanial – I believe that the REST ALM API is not available until ALM version 11.

vineeth varghese - December 1, 2014

Hi Joe,

Could you please tell me how to update a test status in test lab using java code so that i can update the test status after execution of my junit tests.

please help

Vineeth Varghese

    vineeth varghese - December 5, 2014

    Hi Joe,

    We have a requirement to update the test case id in QC after executing our selenium automation test cases using Bamboo. Could you please help me to get some idea on doing this. Please advise

    Vineeth Varghese

Yeshaswini - December 30, 2014

I am trying to create a testcase in QC using REST, I refered the documentation examples “createDeleteExample” where it is there for “requirements”. I tried the similar way for creating test, “login ” happens, but throws exception during “post” operation. Response code returned is “500” – Internal server error.
i have used in the request header the following xml schema
String entityToPostXml =
+ Double.toHexString(Math.random()) + “”);
Why that exception return code”500″ occured?

Nida - February 26, 2015

How can I post testcase to ALM 11 in a Folder using Rest APIs

Bob F. - March 24, 2015

How do I run the REST query using UFT? I logged into ALM beforehand as described but receive the error below. Through a browser the queriy works, but not through UFT. UFT doesn’t seem to recognize the cookie.


Error Step ‘Method4’ : HTTP/1.1 401 Authentication failed. Browser based integrations – to login append ‘?login-form-required=y to the url you tried to access.

Cedwic - March 31, 2015

Quality Center is a powerfull testing process tool. Including as well defect managment.

As a QA manager, my main problematic was to manage several defects coming from many QC projects. And so, how to gather all these defect in an unic view.
Other topic, developers working with ubuntu or any else OS other than internet explorer that should be able to the list of defect…

Got it with QC DASHBOARD!

A web client for Quality Center, runnable from any web browser (Opera, Firefox, Chrome), which also provides an responsive and unified view for all my Quality Center projects.
Simple and clear web interface, it’s also usefull to get dedicated business views, for instance to prepare my next releases, display directly latest created defect and many other features.

Let’s share it :

qc_naive - April 9, 2015


I am trying to access the rest API via python. However, I seem to be unable to authenticate. Would you have any sample python code that I can use as an example?
I want to download the defects from ALM to Excel sheet by applying filters.

robin - May 14, 2015

Can you please let me know how to update a requirement status using rest api.The example shows for read.

Sri - August 6, 2015

Hi Joe,

Really it is a good article.

I am trying to login ALM,and navigate to test lab ,then click on test set ,needs to execute using RUN button in test lab is it possible?

if so please suggest me how to do this using automation .


sandya - November 4, 2015

how to connect qtp with the rest api

Shekar Lakshmipathi - November 18, 2015

I am running some tests and want to create defects on HP QC using the REST APIs – programatically.

Let’s say some of the tests fail every day and it will take 30 days for it to be fixed. I want to create a defect on the first day, and NOT on subsequent runs. How can I know that a defect has been created (or not created).

Vijen - November 23, 2015

Specflow and HP ALM Integration
I am looking for a solution on Specflow and HP ALM Integration.
Can anyone help me out on this ?

    Joe Colantonio - November 23, 2015

    What are you looking for? You could manage both of them using a CI tool like Jenkins

qc_naive - January 4, 2016


I have the following issue and need a solution

1. I want to pull the Test case Execution count using REST API based on the Test Lab Folder name. There can be many test sets inside that test lab folder and even test folders.
Eg: Test Folder 1\Test Folder 2\Test Folder 3\Test Set 1

I need to pull the execution count ( No. of Pass,Fail,No Run etc.,) by giving the parent test lab folder (Test Folder 1).

2.I want to pull the ALM defects using REST API . I have many Favorites in my ALM as Public and Private . Is there a way i can pull the those using REST API ?

3. I want to pull the number of test cases linked to a defect using REST API . I am able to pull the defects but not the linked test cases

Can you please help me with these ?

Sarang - March 21, 2016

Did anyone tried using CURL and get the authentication?

Basically here’s what I tried

Step 1: Tried below and get response

-> curl http://QCURL/qcbin/rest/is-authenticated

Error 401 Authentication failed. Browser based integrations – to login append ‘?login-form-required=y’ to the url you tried to access.

Problem accessing /qcbin/rest/is-authenticated. Reason:
Authentication failed. Browser based integrations – to login append ‘?login-form-required=y’ to the url you tried to access.Powered by Jetty://

Step 2: Tried below and didnt get any response back.

-> curl http://QCURL/qcbin/rest/is-authenticated?login-form-required=y


How to pass user name and password using CURL

    Joe Colantonio - March 29, 2016

    What version of ALM are you using? I think with ALM 12.x they changed the url from /qcbin/rest to /qcbin/api

Sohaib - May 25, 2016

here is a complete reference by HP

what this reference is missing is that after you have authenticated you must do a POST to /qcbin/rest/site-session this will give you two cookies XSRF-TOKEN and QCSESSION see here

Once you have gotten those two cookies you can delete, update and create entities.

I hope this helps.

MVC - June 15, 2016

Hi friends, I need some help as I’m going crazy trying to solve a problem.

In a Visual Basic macro I firstly authenticate an user and then I get session cookies, as specified in the previous post. After that, I launch some queries to get data from test cases, defects, and so other QC instances.

My problem is that each one of these queries creates a connection (visible in ALM – Site Administration Site Connections). When the macro execution finishes, these connections remain opened…. and last week this produced a (big) problem in the server’s performance.

I’ve implemented in the macro the logic for using “/authentication-point/logout” that releases the authentication cookie and it works because if I run a query after it the server returns 401. The problem is that this does not clear connections in the server.

Do you have any idea?

Thanks in advance for your answers.

Kevin Winters - September 22, 2016

I’m trying to add a run in ALM using the REST API. I can successfully add a test run in the Test Runs page of ALM but back on the Test Lab page I have been unsuccessful. In order to update the test cases in the test set which is displayed on the Test Lab page I need to know the testcycl-id. There is at present no way to get that information. Does anyone have any idea how to get the testcycl-id?

Aneejian - March 22, 2017

I am in the process of creating a tutorial on HP ALM REST API. I am trying to include both browser method and code method. Code versions include both C# and VB.

As of now I have this much

sandeep - August 9, 2017

Get target-rel date
How to get the target-rel date in defects .I am using java to read the defects and converting to jaxb clasess to map the attributes.Now unable to get the target-rel date because in “target-rel ” it is having the value as string and date is in “ReferenceValue”.I want to raed the both the values like ReferenceValue and value inside the target-rel .Please suggest.Thank You

anshu - September 14, 2017


After authentication , i tried to get First Defect , and i am getting error message.

“Exception Id: qccore.general-error”

Click here to add a comment

Leave a comment: