HackerOne users: Testing against this community violates our program's Terms of Service and will result in your bounty being denied.

Tutorial: Setting up and using API to batch create discussions

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 https://github.com/vanilla/vanilla 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, http://mysite.com/vanilla-master/) [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 https://github.com/kasperisager/vanilla-api

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 http://www.unixtimestamp.com/ and copy the timestamp. Paste in above where it says unix-timestamp. Save the file.

Now with your browser go to http://mysite.com/vanilla/get-token.php, 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 https://www.getpostman.com/collections/88c667ea752bc4f0186e

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 http://mysite.com/vanilla/
{{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!


  • thx. for the tutorial.

    I may not provide the completed solution you might desire, but I do try to provide honest suggestions to help you solve your issue.

  • hgtonighthgtonight ∞ · New Moderator

    If you are looking to pre-populate the database with discussions based on a CSV file, I would have parsed it into SQL. Save you $10 at least.

    Also, for purely random dummy data, I like the plugin @R_J made: http://vanillaforums.org/discussion/26297/dummy-data-for-vanilla-2-1b2

    Pretty good tutorial :)

    Search first

    Check out the Documentation! We are always looking for new content and pull requests.

    Click on insightful, awesome, and funny reactions to thank community volunteers for their valuable posts.

  • Edit: You don't have to generate a token for every request. They are valid for about 5 minutes. To extend that, you can edit conf/config.php:

    $Configuration['API']['Expiration'] = strtotime('5 minutes', 0);

  • phreakphreak Vanilla*APP (White Label) & Vanilla*Skins Shop MVP

    @lkj897: Late, but still: Thanx for this introduction! :)

    • VanillaAPP | iOS & Android App for Vanilla - White label app for Vanilla Forums OS
    • VanillaSkins | Plugins, Themes, Graphics and Custom Development for Vanilla
  • WARNING: TUTORIAL IS INCORRECT. You must supply both a Content-Type and an Accept header in order to get api to work. Both can be set to "application/json".

  • I am using curl, I am getting error

    <?php $data = array( "Name" => "Test", "Body" => "Test New Testseries 2018", "CategoryID" => "65", "username" => "root", "email" => "root@example.com", "timestamp" => time() ); ksort($data, SORT_STRING); $signature = hash_hmac("sha256", strtolower(implode("-", $data)), "a2fde66c-0ffe-4024-ad89-0f443db2694f"); $data['token'] = $signature; $data_string = json_encode($data,true); $ch = curl_init('http://xyv.example.com/api/discussions'); curl_setopt($ch, CURLOPT_POST, 1); //curl_setopt($ch, CURLOPT_COOKIE, $_SERVER["HTTP_COOKIE"]); curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Content-Length: ' . strlen($data_string)), "Accept: application/json" ); curl_setopt($ch, CURLOPT_HEADER, 1); curl_setopt($ch, CURLINFO_HEADER_OUT, true); $result = curl_exec($ch); curl_close($ch); print_r($result); echo json_decode($result,true); //echo $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE); //echo $contenttype = curl_getinfo($ch, CURLINFO_CONTENT_TYPE); ?>

    I have used latest release 0.5.0 vanilla api

  • I am getting this error: { "Code": 400, "Exception": "Unsupported content type: /" }

  • lgeorgelgeorge New
    edited November 2019

    im trying to authenticate in postman with a local setup

    im getting the key like that, with the secret form the user, from the backend


    $Request = array();

    $Request['username'] = 'root';

    $Request['email'] = 'gliatopoulos@cognity.gr';

    //$Request['timestamp'] = '1572512993';


    echo $Request['timestamp']."<br>";

    ksort($Request, SORT_STRING);

    // Delimit the data values with a dash

    $Request = implode('-', $Request);

    $Token = hash_hmac('sha256', strtolower($Request), $secret);

    echo $Token;

    im getting the token and sending this from postman


    the result is


    "message": "You need one of Garden.Users.Add, Garden.Users.Edit, Garden.Users.Delete permissions to do that.",

    "status": 403,

    "permissions": [





    "description": null


Sign In or Register to comment.