Working with the Kanka API

The Kanka API allows you to interact with your campaign using a programming language of your choice. You can find the documentation by following this link.

Why would I need the API?

There are several reasons why you would want to use the Kanka API. The following are the most common among our community.

Importing campaign data from another program or source. For example, if you have all of your worldbuilding somewhere else and want to transfer to Kanka, you can write a script that will automate this process.
Building external tools. Wrote a custom tool to help with running your game, or a random generator? The Kanka API is perfect for this use case, where your tool interacts with the data in your campaign.
Custom Exports. Want to export your campaign to another tool, or to a custom format.

Setting yourself up

The easiest way to start playing with the API is by using an application like Postman or Hoppscotch. We’ll need to provide headers as explained in the docs. The following headers are required.

authorization: bearer <kanka-user-token>
accept: application/json

To generate a new kanka-user-token, go to your profile API settings.

Postman Example

Set up Postman with the following configuration to get a list of your campaigns.

postman kanka api authorization — Postman: authorization

postman kanka api headers — Postman: headers

Clicking on “Send” should get a list of your campaigns in a JSON format. It should look something like this in Postman.

postman result — Postman: list of campaigns

If you get another result, check out the troubleshooting page in the api docs.

Postman limitations

While you can interact with most features of the Kanka API using Postman, one limitation is uploading images. For this you will need a programming language like Python.

What next?

Now that you’ve set up some example API requests using Postman, you can export them to your code. To do so, click on the “Code” button on the topish right of your request, as highlighted in the following screenshot.

postman code export — Postman: code export

This allows you to export your request to various programming languages.

Code Examples

You can find examples of applications interacting the Kanka API on Github under the Kanka tag. There you can find examples in javascript, python and other languages to get you started.

If you need any help, drop by the Discord and ask in the #development-talk channel.