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"

Create new asset with given parameters.

POST /data/projects/{project_id}/asset-types/{asset_type_id}/assets/new
Jwt authorization

Path parameters

Responses

  • 201

    New asset resource created

POST /data/projects/{project_id}/asset-types/{asset_type_id}/assets/new 
curl \
 --request POST 'http://api.example.com/data/projects/{project_id}/asset-types/{asset_type_id}/assets/new' \
 --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 a model corresponding at given ID and return it as a JSON object.

GET /data/projects/{instance_id}
Jwt authorization

Responses

GET /data/projects/{instance_id} 
curl \
 --request GET 'http://api.example.com/data/projects/{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/day-offs/
Jwt authorization

Filters can be specified in the query string.

Responses

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

Create a model with data given in the request body.

POST /data/day-offs/
Jwt authorization

JSON format is expected. The model performs the validation automatically when instantiated.

Responses

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

Create a model with data given in the request body.

POST /data/status-automations/
Jwt authorization

JSON format is expected. The model performs the validation automatically when instantiated.

Responses

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

Retrieve all entries for given model.

GET /data/search-filters/
Jwt authorization

Filters can be specified in the query string.

Responses

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

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

GET /data/news/{instance_id}
Jwt authorization

Responses

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

Update a model with data given in the request body.

PUT /data/milestones/{instance_id}
Jwt authorization

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

Responses

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

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

GET /data/subscriptions/{instance_id}
Jwt authorization

Responses

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

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

DELETE /data/preview-background-files/{instance_id}
Jwt authorization

Responses

  • 204

    Model deleted

  • 400

    Statement or integrity error

  • 404

    Instance non-existant

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

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

DELETE /data/salary-scales/{instance_id}
Jwt authorization

Responses

  • 204

    Model deleted

  • 400

    Statement or integrity error

  • 404

    Instance non-existant

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

Retrieve all entries for given model.

GET /data/plugins
Jwt authorization

Filters can be specified in the query string.

Responses

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

Retrieve all edit entries.

GET /data/edits/all
Jwt authorization

Filters can be specified in the query string.

Responses

GET /data/edits/all 
curl \
 --request GET 'http://api.example.com/data/edits/all' \
 --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"

Create new working file.

POST /data/tasks/{task_id}/working-files/new
Jwt authorization

A working file is a file used to produce output files. It is the file the CG artist is working on. It is versioned, tied to a task and a software and requires a comment each time it is created. A path is generated for each file created. The path format is defined in the file tree template file.

Path parameters

Responses

  • 201

    New working file created

  • 400

    Given working file already exists

POST /data/tasks/{task_id}/working-files/new 
curl \
 --request POST 'http://api.example.com/data/tasks/{task_id}/working-files/new' \
 --header "Authorization: $API_KEY"

Get last revisions of output files for given instance grouped by output type and file name.

GET /data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-files/last-revisions
Jwt authorization

Responses

  • 200

    Last revisions of output files for given instance grouped by output type and file name

GET /data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-files/last-revisions 
curl \
 --request GET 'http://api.example.com/data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-files/last-revisions' \
 --header "Authorization: $API_KEY"

Get all output files for given poject.

GET /data/projects/{project_id}/output-files
Jwt authorization

Responses

  • 200

    All output files for given project.

GET /data/projects/{project_id}/output-files 
curl \
 --request GET 'http://api.example.com/data/projects/{project_id}/output-files' \
 --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"

Get API name and version.

GET /
Jwt authorization

Responses

  • 200

    API name and version

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

Retrieve a single given news related to a given project

GET /data/projects/{project_id}/news/{news_id}
Jwt authorization

Responses

  • 200

    Single given news related to given project

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

Remove a user from given department.

DELETE /actions/persons/{person_id}/departments/{department_id}
Jwt authorization

Responses

  • 204

    User removed from given department

DELETE /actions/persons/{person_id}/departments/{department_id} 
curl \
 --request DELETE 'http://api.example.com/actions/persons/{person_id}/departments/{department_id}' \
 --header "Authorization: $API_KEY"

Download a thumbnail.

GET /pictures/previews/preview-files/{instance_id}.png
Jwt authorization

Responses

  • 200

    Thumbnail downloaded

  • 403

    Instance not allowed

  • 404

    Picture file not found

GET /pictures/previews/preview-files/{instance_id}.png 
curl \
 --request GET 'http://api.example.com/pictures/previews/preview-files/{instance_id}.png' \
 --header "Authorization: $API_KEY"

Return all projects listed in database.

GET /data/projects/all
Jwt authorization

Ensure that user has at least the manager level before that.

Responses

  • 200

    All projects listed in database

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

Add a person to a production team.

POST /data/projects/{project_id}/team
Jwt authorization

Path parameters

Responses

  • 201

    Person added to the production team

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

Get all metadata descriptors

GET /data/projects/{project_id}/metadata-descriptors
Jwt authorization

It serves to describe extra fields listed in the data attribute of entities.

Responses

  • 200

    All metadata descriptors

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

Delete a metadata descriptor.

DELETE /data/projects/{project_id}/metadata-descriptors/{descriptor_id}
Jwt authorization

Descriptors serve to describe extra fields listed in the data attribute of entities.

Responses

DELETE /data/projects/{project_id}/metadata-descriptors/{descriptor_id} 
curl \
 --request DELETE 'http://api.example.com/data/projects/{project_id}/metadata-descriptors/{descriptor_id}' \
 --header "Authorization: $API_KEY"

Retrieve time spents for given production

GET /data/projects/{project_id}/time-spents
Jwt authorization

Responses

  • 200

    All time spents of given production

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

Delete a budget for given production

DELETE /data/projects/{project_id}/budgets/{budget_id}
Jwt authorization

Responses

DELETE /data/projects/{project_id}/budgets/{budget_id} 
curl \
 --request DELETE 'http://api.example.com/data/projects/{project_id}/budgets/{budget_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"

Retrieve all subcriptions to tasks related to given project.

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

It's mainly used for synchronisation purpose.

Responses

  • 200

    All subcriptions to tasks related to given project

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

Add given timeframe to time spent by a person on a task for a given day.

POST /actions/tasks/{task_id}/time-spents/{date}/persons/{person_id}/add
Jwt authorization

Path parameters

Responses

  • 201

    Given timeframe added to time spent by given person on given task for given day

  • 404

    Wrong date format

POST /actions/tasks/{task_id}/time-spents/{date}/persons/{person_id}/add 
curl \
 --request POST 'http://api.example.com/actions/tasks/{task_id}/time-spents/{date}/persons/{person_id}/add' \
 --header "Authorization: $API_KEY"

Return shots related to given sequence if the current user has access

GET /data/user/sequences/{sequence_id}/shots
Jwt authorization

to it.

Responses

  • 200

    Shots related to given sequence

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

Return true if current user has subscribed to given sequence and

GET /data/user/entities/{sequence_id}/task-types/{task_type_id}/subscribed
Jwt authorization

task type.

Responses

  • 200

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

GET /data/user/entities/{sequence_id}/task-types/{task_type_id}/subscribed 
curl \
 --request GET 'http://api.example.com/data/user/entities/{sequence_id}/task-types/{task_type_id}/subscribed' \
 --header "Authorization: $API_KEY"

Create a subscription entry for given sequence,

POST /actions/user/sequences/{sequence_id}/task-types/{task_type_id}/subscribe
Jwt authorization

task type and current user.

Path parameters

Responses

  • 201

    Subscription entry created

POST /actions/user/sequences/{sequence_id}/task-types/{task_type_id}/subscribe 
curl \
 --request POST 'http://api.example.com/actions/user/sequences/{sequence_id}/task-types/{task_type_id}/subscribe' \
 --header "Authorization: $API_KEY"