All requests should go to http://api.kudobox.co.

1. Authenticate

The only possible way of authentication is Twitter. The logic is described below:

  • your application makes request to /auth/twitter. The request should be done in any browser-like widget or environment.
  • Kudobox redirects a user to a standard Twitter authentication window where the user enters a login and password and grants rights to Kudobox to share tweets
  • Twitter redirects the user back to Kudobox. Kudobox retrieves and saves an authentication token for the future requests
  • Kudobox generates a page with sessionId in it which should be retrieved by your application

Generated sessionId should be passed in all consequent requests to Kudobox API.

2. List Templates

Retrieve templates for kudo cards

GET /templates/

The response format:

   "id": 1,
   "url": "/template/1.png",
}, {
   "id": 2,
   "url": "/template/2.png"

3. Generate Kudo

To allow your cards look identical to the ones generated by the service we decided to share the widget for card generation. You can find the widget over here. The integration points are:

  1. index.html where you should add listener for new card creation
  2. main.js where you should update initHandlers function to listen and fire events between the widget and your application

There are several events your application can fire/listen for to interact with the widget:

  • createCard fired by the application and used to initialize a new kudo card in the widget. For examples check index.html
  • contentchanged fired by the widget when a text on a kudo is changed. For examples check main.js
  • changeFont fired by the application and used to change a font on a kudo. For examples check main.js
  • generateKudo fired by the application and used to notify the widget to produce a ready-to-share kudo card. For examples check main.js
  • kudoReady fired by the widget and used to pass the content of a kudo and its image to the application. For examples check main.js

4. Share Kudo

Upload a kudo and share it on Twitter

POST /kudo/

Required Parameters

Name Type Description
image base64-encoded string Ready-to-share image of kudo with text
text string Text on the kudo card
template integer ID of template used for the card
fontId integer ID of font used for the card
message string Message to share on Twitter
sessionId string ID of current session


1. Sending invalid data will result in a 400 Bad Request response.

HTTP/1.1 400 Bad Request
Content-Length: 35

{"message":"Validation failed"}

2. If the server is not able to share a kudo it will return a 500 Server Error.

HTTP/1.1 500 Server Error
Content-Length: 35

{"message":"Failed to share kudo"}

3. If the server is not able to save a kudo it will return a 500 Server Error.

HTTP/1.1 500 Server Error
Content-Length: 35

{"message":"Failed to save kudo"}

5. List Kudos

Retrieve a list of kudos created by user

GET /kudos/:offset/:limit?sessionId=31231321

The response format:

   "id": 120,
   "text": "My #kudo to @skotlov via http://kudobox.co",
   "card": {
      "url": "http://api.kudobox.co/card/2zDQyNeKNKg4XhQ74qN1dKg.png",
   "tweet": {
       "id": 72,
       "share_id": 120,
       "remote_id": 4234234234,
       "retweet_count": 0,
       "favourite_count": false,

Explore Kudobox

Follow us on:

Email us at skotlov@gmail.com