Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Try Vanilla Forums Cloud product
Vanilla 2.6.1 is here with critical security patches. One of them has been publicly disclosed.

Tutorial: Setting up and using API to batch create discussions

This discussion is related to the API addon.
lkj897lkj897 New
edited August 2014 in Feedback

I wanted to use the Vanilla API, but I'm not a programmer, and even though I read through the documentation many times and asked a couple of people, I didn't really get the help necessary to install and run this as a 'newbie.' So I spend two days fooling around and figured it out myself! I hope this tutorial helps you, but keep in mind it's supplied for educational purposes only, and I can't be held accountable for any of the information presented here or provide additional guidance. Good luck!


Go to and download ZIP. This is the 2.2 'master' version (if you download the stable release (2.1), API won't work.

Upload the ZIP to the desired location on your server, and extract.


Using something like MySQL Database WIzard in your host account's control panel, create a new database and make note of the username, password, etc.

On your browswer, go to the directory where you installed Vanilla (eg, [Note: If you get a blank page, it might be because your PHP version is lower than 5.3]

Enter the details of the database you just created. You will need the admin username and email later to create the token.

You should now be able to access the dashboard and your Vanilla forum.


Download ZIP of Kasper's API from

Upload to your vanilla/applications folder and extract.

Rename folder 'vanilla-api-master' to 'api'

Go to the Vanilla dashboard, find Addons on the sidebar, and click applications.

Enable Vanilla API. Click Settings and take note of the endpoint URL and the API Secret key.


On the Vanilla folder in your server, create a file called something like get-token.php

Put the following code in the file:

< ?php
$Request = array();
$Request['username'] = 'your-admin-name';
$Request['email'] = 'your-admin-email';
$Request['timestamp'] = 'unix-timestamp';
ksort($Request, SORT_STRING);
// Delimit the data values with a dash
$Request = implode('-', $Request);
$Token = hash_hmac('sha256', strtolower($Request), $secret);
echo $Token
? >

The secret, username and email parameters are self-explanatory (obtaining Secret is explained in the previous step).

For the unix-timestamp, go to a site like and copy the timestamp. Paste in above where it says unix-timestamp. Save the file.

Now with your browser go to, and you should see a token. Copy it and use it in the next step.

Note: These tokens can only be used once per request, so for every request you will have to get a new timestamp, edit your get-token.php file, and refresh the get-token.php page to get a new token. There is a way to automate and pass keys without doing all of this, but that's beyond the scope of this tutorial. Also, once you are done you may want to delete the get-token.php file and not leave it around, since it contains your secret.


Using Chrome browser, go to the App store, and install the Postman - REST client. This is the app you will use to issue API requests.

You can download Kasper's API collection by clicking on Import Collection, and entering the URL

You should now see a bunch of folders with APIs for Activities, Categories, etc.

You can run a test by going to the GET/configuration API. Enter the necessary information for the ULR params:

{{domain}} : your vanilla URL API endpoint, such as
{{username}} : the admin user name you used to install Vanilla
{{email}} : the admin emai you used to install Vanilla
{{timestamp}} : the unix timestamp you generated and put in your get-token.php
{{token}} : the token generated through your get-token.php file

As far as Headers, remove the Accept and write Content-Type for Header, and application/json for value.

You should then be able to click Send and get the configuration results.

Similarly, you can now use any of the API by supplying the required info (remember to generate a new timestamp and token each time). Note that for some requests like POST/discussion you need to suply parameters (Name, Body, CategoryID) in the raw tab of presets (select JSON from the drop down menu).


I started all of this because I wanted to use the API to batch create a bunch of categories and discussions without having to do it manually one by one. Postman allows you to do this through the Collection Runner ($10 to add to your client!).

Basically, in the raw tab you would enter something with variables like this:

"Name": "{{discussion-name}}",
"Body": "{{discussion-body}}",
"CategoryID": 1

Then you need to create a csv file with the following strucutre:


(Note: When I created this in Excel, it didn't like the format of the line endins, so I had to change the line endings from Mac to Unix by re-saving it in TextWrangler)

You then go to the Collection Runner, select the collection you want to run (you may want to create a new folder with just your copy of the POST/Discussion API), enter the iterations (number of lines or requests in your csv file), select the csv file, and click Start. Voila!



Sign In or Register to comment.