Kitsu API
0.20.44

Base URL 
http://api.example.com

Welcome to the Kitsu API specification

Version: 0.20.44

The Kitsu API allows to store and manage the data of your animation/VFX production. Through it you can link all the tools of your pipeline and make sure they are all synchronized.

An easy to use Python client to access this API is available: Python Kitsu Client documentation

Authentication

Before you can use any of the endpoints outline below, you will have to get a JWT token to authorize your requests.

You will find the information to retrieve it in the Zou documentation.

OpenAPI definition

This is version 0.20.44 of this API documentation. Last update on May 20, 2025.

This API is provided under license AGPL 3.0.

Log in user by creating and registering auth tokens.

POST /auth/login
Jwt authorization

Login is based on email and password. If no user match given email and a destkop ID, it looks in matching the desktop ID with the one stored in database. It is useful for clients that run on desktop tools and that don't know user email.

Responses

POST /auth/login 
curl \
 --request POST 'http://api.example.com/auth/login' \
 --header "Authorization: $API_KEY"

Retrieve all entities that are not shot, sequence, episode, or edit.

GET /data/assets/with-tasks
Jwt authorization

Adds project name and asset type name and all related tasks.
If episode_id is given as parameter, it returns assets not linked
to an episode and assets linked to given episode.

Responses

  • 200

    All assets with tasks

GET /data/assets/with-tasks 
curl \
 --request GET 'http://api.example.com/data/assets/with-tasks' \
 --header "Authorization: $API_KEY"

Share or unshare a list of assets.

POST /actions/assets/share
Jwt authorization

Responses

  • 201

    All assets modified.

POST /actions/assets/share 
curl \
 --request POST 'http://api.example.com/actions/assets/share' \
 --header "Authorization: $API_KEY"

Retrieve all shared assets used in project episode.

GET /data/projects/{project_id}/episodes/{episode_id}/assets/shared-used
Jwt authorization

Responses

  • 200

    All shared assets used in project episode

GET /data/projects/{project_id}/episodes/{episode_id}/assets/shared-used 
curl \
 --request GET 'http://api.example.com/data/projects/{project_id}/episodes/{episode_id}/assets/shared-used' \
 --header "Authorization: $API_KEY"

Remove an asset instance from given shot.

DELETE /data/shots/{shot_id}/asset-instances/{asset_instance_id}
Jwt authorization

Responses

  • 204

    Asset instance removed from given shot

DELETE /data/shots/{shot_id}/asset-instances/{asset_instance_id} 
curl \
 --request DELETE 'http://api.example.com/data/shots/{shot_id}/asset-instances/{asset_instance_id}' \
 --header "Authorization: $API_KEY"

Retrieve all entries for given model.

GET /data/project-status
Jwt authorization

Filters can be specified in the query string.

Responses

GET /data/project-status 
curl \
 --request GET 'http://api.example.com/data/project-status' \
 --header "Authorization: $API_KEY"

Update a model with data given in the request body.

PUT /data/project-status/{instance_id}
Jwt authorization

JSON format is expected. Model performs the validation automatically when fields are modified.

Responses

PUT /data/project-status/{instance_id} 
curl \
 --request PUT 'http://api.example.com/data/project-status/{instance_id}' \
 --header "Authorization: $API_KEY"

Retrieve all entries for given model.

GET /data/entity-types
Jwt authorization

Filters can be specified in the query string.

Responses

GET /data/entity-types 
curl \
 --request GET 'http://api.example.com/data/entity-types' \
 --header "Authorization: $API_KEY"

Retrieve all entries for given model.

GET /data/organisations
Jwt authorization

Filters can be specified in the query string.

Responses

GET /data/organisations 
curl \
 --request GET 'http://api.example.com/data/organisations' \
 --header "Authorization: $API_KEY"

Retrieve a software corresponding at given ID and return it as a

GET /data/softwares/{instance_id}
Jwt authorization

JSON object.

Responses

GET /data/softwares/{instance_id} 
curl \
 --request GET 'http://api.example.com/data/softwares/{instance_id}' \
 --header "Authorization: $API_KEY"

Retrieve all entries for given model.

GET /data/output-types
Jwt authorization

Filters can be specified in the query string.

Responses

GET /data/output-types 
curl \
 --request GET 'http://api.example.com/data/output-types' \
 --header "Authorization: $API_KEY"

Delete a model corresponding at given ID and return it as a JSON object.

DELETE /data/output-types/{instance_id}
Jwt authorization

Responses

  • 204

    Model deleted

  • 400

    Statement or integrity error

  • 404

    Instance non-existant

DELETE /data/output-types/{instance_id} 
curl \
 --request DELETE 'http://api.example.com/data/output-types/{instance_id}' \
 --header "Authorization: $API_KEY"

Update a model with data given in the request body.

PUT /data/playlists/{instance_id}
Jwt authorization

JSON format is expected. Model performs the validation automatically when fields are modified.

Responses

PUT /data/playlists/{instance_id} 
curl \
 --request PUT 'http://api.example.com/data/playlists/{instance_id}' \
 --header "Authorization: $API_KEY"

Retrieve all entries for given model.

GET /data/schedule-items/
Jwt authorization

Filters can be specified in the query string.

Responses

GET /data/schedule-items/ 
curl \
 --request GET 'http://api.example.com/data/schedule-items/' \
 --header "Authorization: $API_KEY"

Retrieve a model corresponding at given ID and return it as a JSON object.

GET /data/chats/{instance_id}
Jwt authorization

Responses

GET /data/chats/{instance_id} 
curl \
 --request GET 'http://api.example.com/data/chats/{instance_id}' \
 --header "Authorization: $API_KEY"

Update a model with data given in the request body.

PUT /data/studios/{instance_id}
Jwt authorization

JSON format is expected. Model performs the validation automatically when fields are modified.

Responses

PUT /data/studios/{instance_id} 
curl \
 --request PUT 'http://api.example.com/data/studios/{instance_id}' \
 --header "Authorization: $API_KEY"

Retrieve all edit entries.

GET /data/edits
Jwt authorization

Filters can be specified in the query string.

Responses

GET /data/edits 
curl \
 --request GET 'http://api.example.com/data/edits' \
 --header "Authorization: $API_KEY"

Retrieve all preview files linked to a given entity.

GET /data/entities/{entity_id}/preview-files
Jwt authorization

Responses

  • 200

    All preview files linked to given entity

GET /data/entities/{entity_id}/preview-files 
curl \
 --request GET 'http://api.example.com/data/entities/{entity_id}/preview-files' \
 --header "Authorization: $API_KEY"

Export as csv.

GET /export/csv/time-spents.csv
Jwt authorization

Responses

GET /export/csv/time-spents.csv 
curl \
 --request GET 'http://api.example.com/export/csv/time-spents.csv' \
 --header "Authorization: $API_KEY"

Generate an output file path from file tree template

POST /data/entities/{entity_id}/output-file-path
Jwt authorization

Generate file path based on several parameters: entity, output type, task type, revision, mode, name and separator. Revision can be computed automatically as next revision if not given.

Path parameters

Responses

  • 200

    Output file path generated

  • 400

    Malformed file tree

POST /data/entities/{entity_id}/output-file-path 
curl \
 --request POST 'http://api.example.com/data/entities/{entity_id}/output-file-path' \
 --header "Authorization: $API_KEY"

Import shotgun resource.

POST /import/shotgun/notes
Jwt authorization

Responses

POST /import/shotgun/notes 
curl \
 --request POST 'http://api.example.com/import/shotgun/notes' \
 --header "Authorization: $API_KEY"

Import remove instance.

POST /import/shotgun/remove/asset
Jwt authorization

Responses

POST /import/shotgun/remove/asset 
curl \
 --request POST 'http://api.example.com/import/shotgun/remove/asset' \
 --header "Authorization: $API_KEY"

Return a table giving time spent by user and by week for given year.

GET /data/persons/time-spents/week-table/{year}
Jwt authorization

Responses

  • 200

    Table giving time spent by user and by week for given year

GET /data/persons/time-spents/week-table/{year} 
curl \
 --request GET 'http://api.example.com/data/persons/time-spents/week-table/{year}' \
 --header "Authorization: $API_KEY"

Return a table giving time spent by user and by day for given year and month.

GET /data/persons/time-spents/day-table/{year}/{month}
Jwt authorization

Responses

  • 200

    Table giving time spent by user and by day for given year and month

GET /data/persons/time-spents/day-table/{year}/{month} 
curl \
 --request GET 'http://api.example.com/data/persons/time-spents/day-table/{year}/{month}' \
 --header "Authorization: $API_KEY"

Retrieve all previews related to a given entity.

GET /data/playlists/entities/{entity_id}/preview-files
Jwt authorization

It sends them as a dict. Keys are related task type ids and values are arrays of preview for this task type.

Responses

  • 200

    All previews related to given entity

GET /data/playlists/entities/{entity_id}/preview-files 
curl \
 --request GET 'http://api.example.com/data/playlists/entities/{entity_id}/preview-files' \
 --header "Authorization: $API_KEY"

Download given playlist build as .mp4.

GET /data/playlists/{playlist_id}/jobs/{build_job_id}/build/mp4
Jwt authorization

Responses

  • 200

    Given playlist build downloaded as .mp4

  • 400

    Build not finished, need to retry later

GET /data/playlists/{playlist_id}/jobs/{build_job_id}/build/mp4 
curl \
 --request GET 'http://api.example.com/data/playlists/{playlist_id}/jobs/{build_job_id}/build/mp4' \
 --header "Authorization: $API_KEY"

Download given playlist as zip.

GET /data/playlists/{playlist_id}/download/zip
Jwt authorization

Responses

  • 200

    Given playlist downloaded as zip

GET /data/playlists/{playlist_id}/download/zip 
curl \
 --request GET 'http://api.example.com/data/playlists/{playlist_id}/download/zip' \
 --header "Authorization: $API_KEY"

Return the list of projects currently running.

GET /data/projects/open
Jwt authorization

Most of the time, past projects are not needed.

Responses

  • 200

    All running projects

GET /data/projects/open 
curl \
 --request GET 'http://api.example.com/data/projects/open' \
 --header "Authorization: $API_KEY"

Search for resource

POST /data/search
Jwt authorization

Responses

  • 200

    List of entities that contain the query

POST /data/search 
curl \
 --request POST 'http://api.example.com/data/search' \
 --header "Authorization: $API_KEY"

Retrieve given shot.

GET /data/shots/{shot_id}
Jwt authorization
GET /data/shots/{shot_id} 
curl \
 --request GET 'http://api.example.com/data/shots/{shot_id}' \
 --header "Authorization: $API_KEY"

Retrieve all assets for a given shot.

GET /data/shots/{shot_id}/assets
Jwt authorization

Responses

  • 200

    All assets for given shot

GET /data/shots/{shot_id}/assets 
curl \
 --request GET 'http://api.example.com/data/shots/{shot_id}/assets' \
 --header "Authorization: $API_KEY"

Retrieve all shots tasks related to a given episode.

GET /data/episodes/{episode_id}/shot-tasks
Jwt authorization

Responses

  • 200

    All shots tasks related to given episode

GET /data/episodes/{episode_id}/shot-tasks 
curl \
 --request GET 'http://api.example.com/data/episodes/{episode_id}/shot-tasks' \
 --header "Authorization: $API_KEY"

Retrieve all assets tasks related to a given episode.

GET /data/episodes/{episode_id}/asset-tasks
Jwt authorization

Responses

  • 200

    All assets tasks related to given episode

GET /data/episodes/{episode_id}/asset-tasks 
curl \
 --request GET 'http://api.example.com/data/episodes/{episode_id}/asset-tasks' \
 --header "Authorization: $API_KEY"

Retrieve given sequence.

GET /data/sequences/{sequence_id}
Jwt authorization

Responses

GET /data/sequences/{sequence_id} 
curl \
 --request GET 'http://api.example.com/data/sequences/{sequence_id}' \
 --header "Authorization: $API_KEY"

Retrieve all scenes related to a given project.

GET /data/projects/{project_id}/scenes
Jwt authorization

Responses

  • 200

    All scenes related to given project

GET /data/projects/{project_id}/scenes 
curl \
 --request GET 'http://api.example.com/data/projects/{project_id}/scenes' \
 --header "Authorization: $API_KEY"

Delete a comment corresponding at given ID.

DELETE /data/tasks/{task_id}/comments/{comment_id}
Jwt authorization

Responses

  • 204

    Comment corresponding at given ID deleted

DELETE /data/tasks/{task_id}/comments/{comment_id} 
curl \
 --request DELETE 'http://api.example.com/data/tasks/{task_id}/comments/{comment_id}' \
 --header "Authorization: $API_KEY"

Return tasks currently assigned to current user and of which status has

GET /data/user/tasks
Jwt authorization

is_done attribute set to false.

Responses

  • 200

    Unfinished tasks currently assigned to current user

GET /data/user/tasks 
curl \
 --request GET 'http://api.example.com/data/user/tasks' \
 --header "Authorization: $API_KEY"

Return tasks requiring feedback for current user departments.

GET /data/user/tasks-to-check
Jwt authorization


If the user is not a supervisor, it returns an empty list.

Responses

  • 200

    Tasks requiring feedback in current user departments.

GET /data/user/tasks-to-check 
curl \
 --request GET 'http://api.example.com/data/user/tasks-to-check' \
 --header "Authorization: $API_KEY"

Retrieve filter groups for current user and only for open projects.

GET /data/user/filter-groups
Jwt authorization

Responses

  • 200

    Filter groups for current user and only for open projects

GET /data/user/filter-groups 
curl \
 --request GET 'http://api.example.com/data/user/filter-groups' \
 --header "Authorization: $API_KEY"

Update given filter group if it's owned by the current user.

PUT /data/user/filter-groups/{filter_group_id}
Jwt authorization

Responses

  • 200

    Given filter group with updated data

PUT /data/user/filter-groups/{filter_group_id} 
curl \
 --request PUT 'http://api.example.com/data/user/filter-groups/{filter_group_id}' \
 --header "Authorization: $API_KEY"

Return true if current user has subscribed to given task.

GET /data/user/tasks/{task_id}/subscribed
Jwt authorization

Responses

  • 200

    True if current user has subscribed to given task, False otherwise

GET /data/user/tasks/{task_id}/subscribed 
curl \
 --request GET 'http://api.example.com/data/user/tasks/{task_id}/subscribed' \
 --header "Authorization: $API_KEY"

Return the list of sequence ids to which the current user has

GET /data/user/projects/{project_id}/task-types/{task_type_id}/sequence-subscriptions
Jwt authorization

subscribed for given task type.

Responses

  • 200

    List of sequence ids to which the current user has subscribed for given task type

GET /data/user/projects/{project_id}/task-types/{task_type_id}/sequence-subscriptions 
curl \
 --request GET 'http://api.example.com/data/user/projects/{project_id}/task-types/{task_type_id}/sequence-subscriptions' \
 --header "Authorization: $API_KEY"

Create a new chat message.

POST /data/entities/{entity_id}/chat/messages
Jwt authorization

Path parameters

  • entity_id Required

    ID of the entity related to the chat

Responses

  • 201

    Chat message created

  • 400

    Not participant of the chat

POST /data/entities/{entity_id}/chat/messages 
curl \
 --request POST 'http://api.example.com/data/entities/{entity_id}/chat/messages' \
 --header "Authorization: $API_KEY"