You need a Kanka account and access to at least one campaign. The authenticated API uses the following base URL:
https://api.kanka.io/1.0All endpoint paths in this documentation are relative to that URL unless a full URL is shown.
Personal access tokens are the simplest option for scripts, bots, and integrations that act as your own Kanka user. Create one from Profile > API.
Tokens expire after 365 days. Never share a token with anyone, including the Kanka team. Store it in an environment variable or secrets manager rather than in source code.
Each authenticated request must include these headers:
Accept: application/json
Authorization: Bearer YOUR_TOKENFor requests with a JSON body, also send:
Content-Type: application/jsonContent-Type is not required for a bodyless GET request. File uploads use multipart/form-data; let your HTTP client generate the multipart boundary.
The following examples verify your token, find a campaign, and list its characters. Replace YOUR_TOKEN and CAMPAIGN_ID with your values.
export KANKA_TOKEN="YOUR_TOKEN"
curl --fail-with-body \
"https://api.kanka.io/1.0/profile" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${KANKA_TOKEN}"A successful response contains a data object with your user information and your current rate_limit.
curl --fail-with-body \
"https://api.kanka.io/1.0/campaigns" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${KANKA_TOKEN}"Copy the id of a campaign from the response.
curl --fail-with-body \
"https://api.kanka.io/1.0/campaigns/CAMPAIGN_ID/characters" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${KANKA_TOKEN}"Responses are JSON and normally wrap the result in a data property. List endpoints also include pagination links and metadata. See Pagination.
Personal access tokens are for integrations that act as one Kanka user. An OAuth application is intended for software used by multiple Kanka users, where each user authorizes access to their own campaigns.
Do not ask users to give your application their personal access tokens. Use the supported OAuth authorization flow instead. This documentation currently does not define a public OAuth authorization and callback flow, so contact the Kanka team before building a multi-user OAuth integration.
The API does not grant access beyond the authenticated user's Kanka permissions. The user must be a member of the campaign, and the user's campaign role or entity permissions must allow the requested action.
This means that a valid token can still receive a 403 response, and a resource that is not visible to the user may appear as 404 or be omitted from a list. Private entities and private properties are filtered according to Kanka's visibility rules.
Treat every token as a password:
Use a disposable campaign for testing. Create, update, and delete requests affect live data immediately. Recovery is available only for deleted entities and posts in eligible premium campaigns; it is not a replacement for backups.
All endpoints documented here are prefixed with 1.0/ when called against the production API. For example, campaigns means https://api.kanka.io/1.0/campaigns.
The limit is applied per authenticated Kanka user, not per IP address or individual token. The default limit is 30 requests per minute. Subscribers receive 90 requests per minute.
The current limit is returned by the profile endpoint as rate_limit. When the limit is exceeded, the API returns 429 Too Many Requests. Clients should slow down and retry later rather than immediately retrying every request.
All tokens belonging to the same user share that user's limit.
Next up: Requests and responses