Kanka logo Kanka

Entities


Entities

Nearly all models in Kanka are based on the concept of entities. A character is an entity, but because of historical choices, there are two actual models. A character is a singular model and endpoint, and a character has both an id and an entity_id value. The id identifies the character against all other characters, while the entity_id identifies the character against all other entities. This can be confusing at first, but should not be an issue with the help of this documentation.

{warning} Please note that all endpoints documented here need to be prefixed with api/1.0/campaigns/{id}. For example, if an endpoint is listed as characters, you should use kanka.io/api/1.0/campaigns/{id}/characters.

Some common entities include:

Common Attributes

Most entities have the following attributes.

Attribute Type Description
id integer The id identifying the object against all other objects of the same type.
name string The name representing the object.
entry string The html description of the object.
image string The local path to the picture of the object.
image_full string The url to the picture of the object.
image_thumb string The url to the thumbnail of the object.
is_private boolean Determines if the object is only visible by admin members of the campaign.
If the user requesting the API isn't a member of the admin role, such objects won't be returned.
entity_id integer The id identifying the objects against all other entities.
tags array An array of tags that the object is related to.
created_at object An object representing when the object was created (server time)
created_by integer The users.id who created the object.
updated_at object An object representing when the object was updated (server time)
updated_by integer The users.id who last updated the object.

Related Entities

There are several models in Kanka which represent objects attached to entities.

With each request to an object (ie. character, location, etc), you can include the following parameter to get those related objects directly.

Parameter Type Description
related integer Set to 1 if you want the entity's related objects

Examples

Method Endpoint Headers
GET/HEAD characters?related=1 Default
GET/HEAD characters/1?related=1 Default

Result

{
    "data": [
        {
            "id": 44,
            "name": "Frejya",
            "entry": "Lorem Ipsum",
            "image": null,
            "image_full": "{url}",
            "image_thumb": "{url}",
            "is_private": false,
            "entity_id": 76,
            "tags": [],
            "created_at": {
                "date": "2017-12-01 09:07:38.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "created_by": null,
            "updated_at": {
                "date": "2017-12-03 12:06:23.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "updated_by": null,
            "location_id": 2,
            "attributes": [],
            "entity_notes": [],
            "entity_events": [
                {
                    "created_at": {
                        "date": "2018-05-04 05:16:04.000000",
                        "timezone_type": 3,
                        "timezone": "UTC"
                    },
                    "created_by": null,
                    "default_order": null,
                    "entity_id": 76,
                    "id": 22,
                    "is_private": false,
                    "name": null,
                    "type": null,
                    "updated_at": {
                        "date": "2018-12-21 09:25:08.000000",
                        "timezone_type": 3,
                        "timezone": "UTC"
                    },
                    "updated_by": null,
                    "value": null
                }
            ],
            "entity_files": [],
            "relations": [],
            "title": null,
            "age": null,
            "sex": null,
            "race_id": null,
            "type": null,
            "family_id": null,
            "is_dead": false,
            "traits": []
        }
    ]
}

Notice the new array objects attributes, entity_files, entity_events, entity_notes and relations.