Requests and Responses

Base URL

Authenticated API requests use:

https://api.kanka.io/1.0

The 1.0 segment is the API version. Endpoint pages show paths relative to this base URL unless they include the full prefix.

Headers

Send these headers with every authenticated request:

Accept: application/json
Authorization: Bearer YOUR_TOKEN

For a JSON request body, add Content-Type: application/json. Do not manually set the multipart boundary for file uploads; your HTTP client should set it when sending multipart/form-data.

Request bodies

JSON request bodies must be valid JSON and use the field names shown on the endpoint page. POST, PUT, and PATCH requests can return 422 Unprocessable Entity when required fields are missing or invalid.

Use PUT or PATCH as documented for each resource. Unless a page says otherwise, PATCH is the better choice when changing only some fields.

Response format

Successful responses generally return JSON. A single resource is normally under data:

{
    "data": {
        "id": 123,
        "name": "Example"
    }
}

Collections use a data array and include links and meta when paginated. A successful delete may return an empty 204 No Content response; follow the endpoint page if its response differs.

Dates are returned as ISO 8601 timestamps in UTC unless the endpoint documents another format.

HTTP methods

Method Typical use
GET Read a collection or resource
POST Create a resource or perform an action
PUT Replace or update a resource
PATCH Partially update a resource
DELETE Delete a resource

Some resource pages list HEAD alongside GET. The API documentation focuses on the JSON response from GET.

Permissions

Requests are evaluated as the user represented by the bearer token. Tokens do not bypass campaign membership, campaign roles, visibility settings, or entity permissions. See Permissions and security and Permissions Test.

See Errors when a request does not return the expected response.