Join 34,000+ subscribers and receive articles from our blog about software quality, testing, QA and security.

Specific formatting for API Requests


I have been trying to get this to work for over 10 hours and I can’t figure this out. Unfortunately, the examples in the documentation aren’t very clear.

What is the specific syntax for sending these requests? Where does the key go? Where do the arguments go? Does the key have to go at the end of the request? The beginning? I have tried every combination and I always get “Error: Key missing or invalid” or “Exceptions must be valid objects derived from the Exception base class in /Applications/MAMP/htdocs/testrail/sys/helpers/ex.php at 23”}"

Needless to say, this is becoming very frustrating for me. Is there any way that I can get a specific example or an explanation with multiple examples of how to access this API with more than 1 argument? Every example I see has 1 argument, but I can’t even get that to work.

I am trying to get this to work on my local machine before I move it into production. I am using MAMP and sending cURL requests using PHP.

Thank you.


Hello Blaine,

Thanks for your posting. You just need to submit a simple POST call to TestRail and submit any arguments as POST arguments. Here’s a simple example on how to do this with PHP and cURL:

So you would just need to build an array with your arguments (i.e. title, priority etc.) and send this request to TestRail. I would suggest starting with just the title and then add more fields once you’ve got this running. The supported fields for adding a test case can be found here, e.g.:

Please make sure to include the API key in the request URL as well (the CURLOPT_URL argument, for example), e.g.:

I hope this helps. Just let me know in case you have any further questions.



Thank you for the clarification.

What is the “2” in side the URL? Is that the user ID?


Hello Blaine,

The ‘2’ in this example specifies the ID of the test case. This was just an example for specifying the API key in the URL and is not the API call to add a test case. The full URL layout is documented in detail on the following page:

The API always runs with the same user ID (as configured via the GI_MINIAPI_USER_ID define in the TestRail PHP file).

I hope this helps,


Can the test case ID be sent via POST argument, or does it have to be attached to the URL?


For the get_case method, it must be attached to the URL. For add_case, you wouldn’t specify a test case ID. Each API call has its own set of arguments and return values, as documented on the following page for test cases, e.g.:

For adding a test case, you would need to add the ID of the section to the URL, e.g.:

I hope this helps,


So the Section ID is just an integer not S1 or S2, but just 1 or 2; right?


Yes, but please note that the section ID is different from the ID of the test suite (which is displayed with the S# syntax in the user interface).



Hi everyone! Tell me please is correct I’m creating the api key?

and when I send to “get post” I receive the next -

What Am I do it wrong?


The API key is not the issue but in the API call itself. There is a header portion to it and it wants a header that is “Accept: application/json”.

I am really only familiar with Postman with API calls where it would look like this:

or this:


Hi Alex,

We recommend using our official API bindings to access TestRail’s API:

I noticed that you are using the old/deprecated mini-API and API keys are only supported by the new API.