zou 0.20.83__py3-none-any.whl → 0.20.84__py3-none-any.whl

zou/app/blueprints/shots/resources.py

@@ -27,10 +27,12 @@ class ShotResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, shot_id):
         """
-        Retrieve given shot.
+        Get shot
         ---
         tags:
         - Shots
+        description: Get a shot by id. Returns full shot data. Use this to fetch
+          a single shot with all fields needed by the UI.
         parameters:
           - in: path
             name: shot_id
@@ -40,7 +42,33 @@ class ShotResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Given shot
+                description: Shot found and returned
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        parent_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        nb_frames:
+                          type: integer
+                          example: 120
+                        data:
+                          type: object
+                          example: {"camera": "camA", "cut_in": 1001}
         """
         shot = shots_service.get_full_shot(shot_id)
         if shot is None:
@@ -53,10 +81,12 @@ class ShotResource(Resource, ArgsMixin):
     @jwt_required()
     def put(self, shot_id):
         """
-        Update given shot.
+        Update shot
         ---
         tags:
         - Shots
+        description: Update a shot by id. Only mutable fields are allowed. Send a
+          JSON body with the fields to change.
         parameters:
           - in: path
             name: shot_id
@@ -70,10 +100,51 @@ class ShotResource(Resource, ArgsMixin):
             application/json:
               schema:
                 type: object
-                description: Shot data to update
+                description: Data to update on the shot
+                properties:
+                  name:
+                    type: string
+                    example: SH010 new name
+                  description:
+                    type: string
+                    example: Update description for the shot
+                  nb_frames:
+                    type: integer
+                    example: 24
+                  data:
+                    type: object
+                    example: {"camera": "camA", "cut_in": 1001}
         responses:
             200:
-                description: Update given shot
+                description: Shot updated
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        parent_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        nb_frames:
+                          type: integer
+                          example: 120
+                        data:
+                          type: object
+                          example: {"camera": "camA", "cut_in": 1001}
+            400:
+                description: Invalid body or unsupported fields
         """
         shot = shots_service.get_shot(shot_id)
         user_service.check_manager_project_access(shot["project_id"])
@@ -102,10 +173,12 @@ class ShotResource(Resource, ArgsMixin):
     @jwt_required()
     def delete(self, shot_id):
         """
-        Delete given shot.
+        Delete shot
         ---
         tags:
         - Shots
+        description: Delete a shot by id. Requires manager access or ownership of
+          the shot.
         parameters:
           - in: path
             name: shot_id
@@ -115,7 +188,7 @@ class ShotResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             204:
-                description: Given shot deleted
+                description: Shot deleted
         """
         force = self.get_force()
         shot = shots_service.get_shot(shot_id)
@@ -131,10 +204,11 @@ class SceneResource(Resource):
     @jwt_required()
     def get(self, scene_id):
         """
-        Retrieve given scene.
+        Get scene
         ---
         tags:
         - Shots
+        description: Get a scene by id. Returns full scene data needed by clients.
         parameters:
           - in: path
             name: scene_id
@@ -144,7 +218,23 @@ class SceneResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Given scene
+                description: Scene found and returned
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SC001
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
         """
         scene = shots_service.get_full_scene(scene_id)
         user_service.check_project_access(scene["project_id"])
@@ -154,10 +244,11 @@ class SceneResource(Resource):
     @jwt_required()
     def delete(self, scene_id):
         """
-        Delete given scene.
+        Delete scene
         ---
         tags:
         - Shots
+        description: Delete a scene by id. Requires manager access or ownership.
         parameters:
           - in: path
             name: scene_id
@@ -167,7 +258,7 @@ class SceneResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             204:
-                description: Given scene deleted
+                description: Scene deleted
         """
         scene = shots_service.get_scene(scene_id)
         if scene["created_by"] == persons_service.get_current_user()["id"]:
@@ -182,11 +273,12 @@ class ShotsResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all shot entries.
+        Get shots
         ---
         tags:
         - Shots
-        description: Filters can be specified in the query string.
+        description: Get shots with optional filters. Use query params like
+          project_id, sequence_id or parent_id to filter results.
         parameters:
           - in: query
             name: sequence_id
@@ -209,6 +301,28 @@ class ShotsResource(Resource):
         responses:
             200:
                 description: All shot entries
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         criterions = query.get_query_criterions_from_request(request)
         if "sequence_id" in criterions:
@@ -228,11 +342,12 @@ class AllShotsResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all shot entries.
+        Get all shots
         ---
         tags:
         - Shots
-        description: Filters can be specified in the query string.
+        description: Get all shots across projects with optional filters. Use
+          sequence_id, project_id, or parent_id to filter.
         parameters:
           - in: query
             name: sequence_id
@@ -255,6 +370,28 @@ class AllShotsResource(Resource):
         responses:
             200:
                 description: All shot entries
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH020
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         criterions = query.get_query_criterions_from_request(request)
         if "sequence_id" in criterions:
@@ -274,11 +411,12 @@ class ScenesResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all scene entries.
+        Get scenes
         ---
         tags:
         - Shots
-        description: Filters can be specified in the query string.
+        description: Get scenes with optional filters. Use project_id to filter
+          by project.
         parameters:
           - in: query
             name: project_id
@@ -289,6 +427,24 @@ class ScenesResource(Resource):
         responses:
             200:
                 description: All scene entries
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SC001
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
         """
         criterions = query.get_query_criterions_from_request(request)
         user_service.check_project_access(criterions.get("project_id", None))
@@ -299,10 +455,12 @@ class ShotAssetsResource(Resource):
     @jwt_required()
     def get(self, shot_id):
         """
-        Retrieve all assets for a given shot.
+        Get shot assets
         ---
         tags:
         - Shots
+        description: Get assets linked to a shot. Returns the breakdown casting
+          for the shot.
         parameters:
           - in: path
             name: shot_id
@@ -313,6 +471,24 @@ class ShotAssetsResource(Resource):
         responses:
             200:
                 description: All assets for given shot
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: Character A
+                          entity_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
         """
         shot = shots_service.get_shot(shot_id)
         user_service.check_project_access(shot["project_id"])
@@ -324,10 +500,11 @@ class ShotTaskTypesResource(Resource):
     @jwt_required()
     def get(self, shot_id):
         """
-        Retrieve all task types related to a given shot.
+        Get shot task types
         ---
         tags:
         - Shots
+        description: Get task types for a shot.
         parameters:
           - in: path
             name: shot_id
@@ -338,6 +515,20 @@ class ShotTaskTypesResource(Resource):
         responses:
             200:
                 description: All task types related to given shot
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: Animation
         """
         shot = shots_service.get_shot(shot_id)
         user_service.check_project_access(shot["project_id"])
@@ -349,10 +540,12 @@ class ShotTasksResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, shot_id):
         """
-        Retrieve all tasks related to a given shot.
+        Get shot tasks
         ---
         tags:
         - Shots
+        description: Get tasks for a shot. Optionally include relations using
+          query params.
         parameters:
           - in: path
             name: shot_id
@@ -363,6 +556,42 @@ class ShotTasksResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All tasks related to given shot
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010 Animation
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: e24a6ea4-ce75-4665-a070-57453082c25
+                          assignees:
+                            type: array
+                            items:
+                              type: string
+                              format: uuid
+                            example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
         """
         shot = shots_service.get_shot(shot_id)
         user_service.check_project_access(shot["project_id"])
@@ -375,10 +604,12 @@ class SequenceShotTasksResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, sequence_id):
         """
-        Retrieve all tasks related to a given sequence.
+        Get sequence shot tasks
         ---
         tags:
         - Shots
+        description: Get shot tasks for a sequence. Restricted for vendor
+          permissions.
         parameters:
           - in: path
             name: sequence_id
@@ -388,7 +619,33 @@ class SequenceShotTasksResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: All task types related to given sequence
+                description: All shot tasks related to given sequence
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010 Animation
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
         """
         sequence = shots_service.get_sequence(sequence_id)
         user_service.check_project_access(sequence["project_id"])
@@ -405,10 +662,12 @@ class EpisodeShotTasksResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, episode_id):
         """
-        Retrieve all shots tasks related to a given episode.
+        Get episode shot tasks
         ---
         tags:
         - Shots
+        description: Get shot tasks for an episode. Restricted for vendor
+          permissions.
         parameters:
           - in: path
             name: episode_id
@@ -418,7 +677,33 @@ class EpisodeShotTasksResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: All shots tasks related to given episode
+                description: All shot tasks related to given episode
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: EP01 Layout
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
         """
         episode = shots_service.get_episode(episode_id)
         user_service.check_project_access(episode["project_id"])
@@ -435,10 +720,12 @@ class EpisodeAssetTasksResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, episode_id):
         """
-        Retrieve all assets tasks related to a given episode.
+        Get episode asset tasks
         ---
         tags:
         - Shots
+        description: Get asset tasks for an episode. Restricted for vendor
+          permissions.
         parameters:
           - in: path
             name: episode_id
@@ -449,6 +736,32 @@ class EpisodeAssetTasksResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All assets tasks related to given episode
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: Character Modeling
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
         """
         episode = shots_service.get_episode(episode_id)
         user_service.check_project_access(episode["project_id"])
@@ -465,10 +778,12 @@ class EpisodeShotsResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, episode_id):
         """
-        Retrieve all shots related to a given episode.
+        Get episode shots
         ---
         tags:
         - Shots
+        description: Get shots for an episode. Supports including relations via
+          query params.
         parameters:
           - in: path
             name: episode_id
@@ -479,6 +794,28 @@ class EpisodeShotsResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All shots related to given episode
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         episode = shots_service.get_episode(episode_id)
         user_service.check_project_access(episode["project_id"])
@@ -493,12 +830,12 @@ class ShotPreviewsResource(Resource):
     @jwt_required()
     def get(self, shot_id):
         """
-        Retrieve all previews related to a given shot.
+        Get shot previews
         ---
         tags:
         - Shots
-        description: It sends them as a dict.
-                     Keys are related task type ids and values are arrays of preview for this task type.
+        description: Return previews for a shot as a dict keyed by task type id.
+          Each value is an array of previews for that task type.
         parameters:
           - in: path
             name: shot_id
@@ -508,7 +845,35 @@ class ShotPreviewsResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: All previews related to given episode
+                description: All previews related to given shot
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      additionalProperties:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            id:
+                              type: string
+                              format: uuid
+                              example: b24a6ea4-ce75-4665-a070-57453082c25
+                            revision:
+                              type: integer
+                              example: 3
+                            file_id:
+                              type: string
+                              format: uuid
+                              example: c24a6ea4-ce75-4665-a070-57453082c25
+                    example:
+                      "a24a6ea4-ce75-4665-a070-57453082c25": [
+                        {
+                          "id": "b24a6ea4-ce75-4665-a070-57453082c25",
+                          "revision": 3,
+                          "file_id": "c24a6ea4-ce75-4665-a070-57453082c25"
+                        }
+                      ]
         """
         shot = shots_service.get_shot(shot_id)
         user_service.check_project_access(shot["project_id"])
@@ -520,10 +885,12 @@ class SequenceTasksResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, sequence_id):
         """
-        Retrieve all tasks related to a given shot.
+        Get sequence tasks
         ---
         tags:
         - Shots
+        description: Get tasks for a sequence. Optionally include relations using
+          query params.
         parameters:
           - in: path
             name: sequence_id
@@ -534,6 +901,36 @@ class SequenceTasksResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All tasks related to given shot
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010 Animation
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: e24a6ea4-ce75-4665-a070-57453082c25
         """
         sequence = shots_service.get_sequence(sequence_id)
         user_service.check_project_access(sequence["project_id"])
@@ -547,10 +944,11 @@ class SequenceTaskTypesResource(Resource):
     @jwt_required()
     def get(self, sequence_id):
         """
-        Retrieve all task types related to a given shot.
+        Get sequence task types
         ---
         tags:
         - Shots
+        description: Get task types for a sequence.
         parameters:
           - in: path
             name: sequence_id
@@ -561,6 +959,20 @@ class SequenceTaskTypesResource(Resource):
         responses:
             200:
                 description: All task types related to given shot
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: Animation
         """
         sequence = shots_service.get_sequence(sequence_id)
         user_service.check_project_access(sequence["project_id"])
@@ -572,10 +984,11 @@ class ShotsAndTasksResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all shots, adds project name and asset type name and all related tasks.
+        Get shots and tasks
         ---
         tags:
         - Shots
+        description: Get shots and their related tasks. Optionally filter by project.
         parameters:
           - in: query
             name: project_id
@@ -586,6 +999,36 @@ class ShotsAndTasksResource(Resource):
         responses:
             200:
                 description: All shots
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          tasks:
+                            type: array
+                            items:
+                              type: object
+                              properties:
+                                id:
+                                  type: string
+                                  format: uuid
+                                  example: c24a6ea4-ce75-4665-a070-57453082c25
+                                name:
+                                  type: string
+                                  example: SH010 Animation
         """
         criterions = query.get_query_criterions_from_request(request)
         user_service.check_project_access(criterions.get("project_id", None))
@@ -604,10 +1047,11 @@ class SceneAndTasksResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all scenes, adds project name and asset type name and all related tasks.
+        Get scenes and tasks
         ---
         tags:
         - Shots
+        description: Get scenes and their related tasks. Optionally filter by project.
         parameters:
           - in: query
             name: project_id
@@ -618,6 +1062,36 @@ class SceneAndTasksResource(Resource):
         responses:
             200:
                 description: All scenes
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SC001
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          tasks:
+                            type: array
+                            items:
+                              type: object
+                              properties:
+                                id:
+                                  type: string
+                                  format: uuid
+                                  example: c24a6ea4-ce75-4665-a070-57453082c25
+                                name:
+                                  type: string
+                                  example: Layout
         """
         criterions = query.get_query_criterions_from_request(request)
         user_service.check_project_access(criterions.get("project_id", None))
@@ -629,10 +1103,12 @@ class SequenceAndTasksResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all sequences, adds project name and asset type name and all related tasks.
+        Get sequences and tasks
         ---
         tags:
         - Shots
+        description: Get sequences and their related tasks.
+          Optionally filter by project.
         parameters:
           - in: query
             name: project_id
@@ -643,6 +1119,36 @@ class SequenceAndTasksResource(Resource):
         responses:
             200:
                 description: All sequences
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SQ010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          tasks:
+                            type: array
+                            items:
+                              type: object
+                              properties:
+                                id:
+                                  type: string
+                                  format: uuid
+                                  example: c24a6ea4-ce75-4665-a070-57453082c25
+                                name:
+                                  type: string
+                                  example: SQ010 Editing
         """
         criterions = query.get_query_criterions_from_request(request)
         user_service.check_project_access(criterions.get("project_id", None))
@@ -654,10 +1160,12 @@ class EpisodeAndTasksResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all episodes, adds project name and asset type name and all related tasks.
+        Get episodes and tasks
         ---
         tags:
         - Shots
+        description: Get episodes and their related tasks.
+          Optionally filter by project.
         parameters:
           - in: query
             name: project_id
@@ -668,6 +1176,36 @@ class EpisodeAndTasksResource(Resource):
         responses:
             200:
                 description: All episodes
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: EP01
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          tasks:
+                            type: array
+                            items:
+                              type: object
+                              properties:
+                                id:
+                                  type: string
+                                  format: uuid
+                                  example: c24a6ea4-ce75-4665-a070-57453082c25
+                                name:
+                                  type: string
+                                  example: EP01 Layout
         """
         criterions = query.get_query_criterions_from_request(request)
         user_service.check_project_access(criterions.get("project_id", None))
@@ -679,10 +1217,12 @@ class ProjectShotsResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve all shots related to a given project.
+        Get project shots
         ---
         tags:
         - Shots
+        description: Get shots for a project. May limit to assigned shots for
+          vendor users.
         parameters:
           - in: path
             name: project_id
@@ -693,6 +1233,28 @@ class ProjectShotsResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All shots related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -703,10 +1265,12 @@ class ProjectShotsResource(Resource, ArgsMixin):
     @jwt_required()
     def post(self, project_id):
         """
-        Create a shot for given project.
+        Create project shot
         ---
         tags:
         - Shots
+        description: Create a shot in a project. Provide name and optional
+          fields like description, sequence_id and nb_frames.
         parameters:
           - in: path
             name: project_id
@@ -726,11 +1290,11 @@ class ProjectShotsResource(Resource, ArgsMixin):
                   name:
                     type: string
                     required: true
-                    example: "Name of shot"
+                    example: SH010
                   description:
                     type: string
                     required: false
-                    example: "Description of shot"
+                    example: A short description of the shot
                   sequence_id:
                     type: string
                     format: uuid
@@ -742,7 +1306,33 @@ class ProjectShotsResource(Resource, ArgsMixin):
                     example: 24
         responses:
             201:
-                description: Shot created for given project
+                description: Shot created
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        sequence_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        nb_frames:
+                          type: integer
+                          example: 24
+                        description:
+                          type: string
+                          example: A short description of the shot
         """
         (
             sequence_id,
@@ -789,10 +1379,12 @@ class ProjectSequencesResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve all sequences related to a given project.
+        Get project sequences
         ---
         tags:
         - Shots
+        description: Get sequences for a project. May limit to assigned items for
+          vendor users.
         parameters:
           - in: path
             name: project_id
@@ -803,6 +1395,28 @@ class ProjectSequencesResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All sequences related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SQ01
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          episode_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -813,10 +1427,12 @@ class ProjectSequencesResource(Resource, ArgsMixin):
     @jwt_required()
     def post(self, project_id):
         """
-        Create a sequence for given project.
+        Create project sequence
         ---
         tags:
         - Shots
+        description: Create a sequence in a project. Provide name and optional
+          episode_id.
         parameters:
           - in: path
             name: project_id
@@ -836,7 +1452,7 @@ class ProjectSequencesResource(Resource, ArgsMixin):
                   name:
                     type: string
                     required: true
-                    example: "Name of sequence"
+                    example: SQ01
                   episode_id:
                     type: string
                     format: uuid
@@ -844,7 +1460,30 @@ class ProjectSequencesResource(Resource, ArgsMixin):
                     example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             201:
-                description: Sequence created for given project
+                description: Sequence created
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SQ01
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        episode_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        description:
+                          type: string
+                          example: A sequence description
         """
         (episode_id, name, description, data) = self.get_arguments()
         projects_service.get_project(project_id)
@@ -881,10 +1520,12 @@ class ProjectEpisodesResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve all episodes related to a given project.
+        Get project episodes
         ---
         tags:
         - Shots
+        description: Get episodes for a project. May limit to assigned items for
+          vendor users.
         parameters:
           - in: path
             name: project_id
@@ -895,6 +1536,30 @@ class ProjectEpisodesResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All episodes related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: EP01
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          description:
+                            type: string
+                            example: A short description of the episode
+                          status:
+                            type: string
+                            example: running
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -905,10 +1570,12 @@ class ProjectEpisodesResource(Resource, ArgsMixin):
     @jwt_required()
     def post(self, project_id):
         """
-        Create an episode for given project.
+        Create project episode
         ---
         tags:
         - Shots
+        description: Create an episode in a project. Provide name and
+          description. Status is optional.
         parameters:
           - in: path
             name: project_id
@@ -929,14 +1596,40 @@ class ProjectEpisodesResource(Resource, ArgsMixin):
                   name:
                     type: string
                     required: true
-                    example: "Name of the episode"
+                    example: EP01
                   description:
                     type: string
                     required: true
-                    example: "Description of the episode"
+                    example: A short description of the episode
+                  status:
+                    type: string
+                    required: false
+                    example: running
         responses:
             201:
-                description: Episode created for given project
+                description: Episode created
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: EP01
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        description:
+                          type: string
+                          example: A short description of the episode
+                        status:
+                          type: string
+                          example: running
         """
         name, status, description, data = self.get_arguments()
         projects_service.get_project(project_id)
@@ -970,10 +1663,12 @@ class ProjectEpisodeStatsResource(Resource):
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve number of tasks by status, task_types and episodes for given project.
+        Get episode stats
         ---
         tags:
         - Shots
+        description: Return number of tasks by status, task type and episode
+          for the project.
         parameters:
           - in: path
             name: project_id
@@ -984,6 +1679,43 @@ class ProjectEpisodeStatsResource(Resource):
         responses:
             200:
                 description: Number of tasks by status, task types and episodes for given project
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      additionalProperties:
+                        type: object
+                        additionalProperties:
+                          type: object
+                          additionalProperties:
+                            type: object
+                            properties:
+                              count:
+                                type: integer
+                                example: 120
+                              frames:
+                                type: integer
+                                example: 1440
+                              drawings:
+                                type: integer
+                                example: 360
+                      example:
+                        episodeId1:
+                          taskTypeId1:
+                            taskStatusId1:
+                              count: 50
+                              frames: 600
+                              drawings: 150
+                            taskStatusId2:
+                              count: 70
+                              frames: 840
+                              drawings: 210
+                        all:
+                          all:
+                            taskStatusId1:
+                              count: 200
+                              frames: 2400
+                              drawings: 600
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -996,10 +1728,12 @@ class ProjectEpisodeRetakeStatsResource(Resource):
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve number of tasks by status, task_types and episodes for given project.
+        Get episode retake stats
         ---
         tags:
         - Shots
+        description: Return retake and done counts by task type and episode.
+          Includes evolution data and max retake count.
         parameters:
           - in: path
             name: project_id
@@ -1010,6 +1744,121 @@ class ProjectEpisodeRetakeStatsResource(Resource):
         responses:
             200:
                 description: Number of tasks by status, task types and episodes for given project
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      additionalProperties:
+                        type: object
+                        properties:
+                          max_retake_count:
+                            type: integer
+                            example: 4
+                          evolution:
+                            type: object
+                            additionalProperties:
+                              type: object
+                              properties:
+                                retake:
+                                  type: object
+                                  properties:
+                                    count:
+                                      type: integer
+                                      example: 80
+                                    frames:
+                                      type: integer
+                                      example: 7900
+                                    drawings:
+                                      type: integer
+                                      example: 8000
+                                done:
+                                  type: object
+                                  properties:
+                                    count:
+                                      type: integer
+                                      example: 117
+                                    frames:
+                                      type: integer
+                                      example: 3900
+                                    drawings:
+                                      type: integer
+                                      example: 8000
+                          done:
+                            type: object
+                            properties:
+                              count:
+                                type: integer
+                                example: 197
+                              frames:
+                                type: integer
+                                example: 16090
+                              drawings:
+                                type: integer
+                                example: 16090
+                          retake:
+                            type: object
+                            properties:
+                              count:
+                                type: integer
+                                example: 0
+                              frames:
+                                type: integer
+                                example: 0
+                              drawings:
+                                type: integer
+                                example: 0
+                          other:
+                            type: object
+                            properties:
+                              count:
+                                type: integer
+                                example: 5
+                              frames:
+                                type: integer
+                                example: 185
+                              drawings:
+                                type: integer
+                                example: 185
+                      example:
+                        episodeId1:
+                          max_retake_count: 4
+                          evolution:
+                            "1":
+                              retake:
+                                count: 80
+                                frames: 7900
+                                drawings: 8000
+                              done:
+                                count: 117
+                                frames: 3900
+                                drawings: 8000
+                          done:
+                            count: 197
+                            frames: 16090
+                            drawings: 16090
+                          retake:
+                            count: 0
+                            frames: 0
+                            drawings: 0
+                          other:
+                            count: 5
+                            frames: 185
+                            drawings: 185
+                        all:
+                          all:
+                            max_retake_count: 4
+                            done:
+                              count: 500
+                              frames: 50000
+                              drawings: 50000
+                            retake:
+                              count: 100
+                              frames: 10000
+                              drawings: 10000
+                            other:
+                              count: 10
+                              frames: 1000
+                              drawings: 1000
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -1022,10 +1871,12 @@ class EpisodeResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, episode_id):
         """
-        Retrieve given episode.
+        Get episode
         ---
         tags:
         - Shots
+        description: Get an episode by id.
+          needs.
         parameters:
           - in: path
             name: episode_id
@@ -1035,7 +1886,29 @@ class EpisodeResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Given episode
+                description: Episode found and returned
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: EP01
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        description:
+                          type: string
+                          example: A short description of the episode
+                        status:
+                          type: string
+                          example: running
         """
         episode = shots_service.get_full_episode(episode_id)
         user_service.check_project_access(episode["project_id"])
@@ -1044,10 +1917,12 @@ class EpisodeResource(Resource, ArgsMixin):
     @jwt_required()
     def delete(self, episode_id):
         """
-        Delete given episode.
+        Delete episode
         ---
         tags:
         - Shots
+        description: Delete an episode by id. Requires manager access or
+          ownership.
         parameters:
           - in: path
             name: episode_id
@@ -1057,7 +1932,7 @@ class EpisodeResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             204:
-                description: Given episode deleted
+                description: Episode deleted
         """
         force = self.get_force()
         episode = shots_service.get_episode(episode_id)
@@ -1073,11 +1948,12 @@ class EpisodesResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all episode entries.
+        Get episodes
         ---
         tags:
         - Shots
-        description: Filters can be specified in the query string.
+        description: Get episodes with optional filters. Use project_id to
+          filter by project.
         parameters:
           - in: query
             name: project_id
@@ -1088,6 +1964,30 @@ class EpisodesResource(Resource):
         responses:
             200:
                 description: All episode entries
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: EP01
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          description:
+                            type: string
+                            example: A short description of the episode
+                          status:
+                            type: string
+                            example: running
         """
         criterions = query.get_query_criterions_from_request(request)
         user_service.check_project_access(criterions.get("project_id", None))
@@ -1098,11 +1998,12 @@ class EpisodeSequencesResource(Resource):
     @jwt_required()
     def get(self, episode_id):
         """
-        Retrieve all sequence entries for a given episode.
+        Get episode sequences
         ---
         tags:
         - Shots
-        description: Filters can be specified in the query string.
+        description: Get sequences for an episode. You can add query filters
+          if needed.
         parameters:
           - in: path
             name: episode_id
@@ -1119,6 +2020,28 @@ class EpisodeSequencesResource(Resource):
         responses:
             200:
                 description: All sequence entries for given episode
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SQ01
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         if not fields.is_valid_id(episode_id):
             return []
@@ -1138,7 +2061,7 @@ class EpisodeTaskTypesResource(Resource):
     @jwt_required()
     def get(self, episode_id):
         """
-        Retrieve all task types related to a given episode.
+        Get episode task types
         ---
         tags:
         - Shots
@@ -1152,6 +2075,20 @@ class EpisodeTaskTypesResource(Resource):
         responses:
             200:
                 description: All task types related to given episode
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: Animation
         """
         episode = shots_service.get_episode(episode_id)
         user_service.check_project_access(episode["project_id"])
@@ -1162,7 +2099,7 @@ class EpisodeTasksResource(Resource):
     @jwt_required()
     def get(self, episode_id):
         """
-        Retrieve all tasks related to a given episode.
+        Get episode tasks
         ---
         tags:
         - Shots
@@ -1176,6 +2113,42 @@ class EpisodeTasksResource(Resource):
         responses:
             200:
                 description: All tasks related to given episode
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: EP01 Layout
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: e24a6ea4-ce75-4665-a070-57453082c25
+                          assignees:
+                            type: array
+                            items:
+                              type: string
+                              format: uuid
+                            example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
         """
         episode = shots_service.get_episode(episode_id)
         user_service.check_project_access(episode["project_id"])
@@ -1186,10 +2159,11 @@ class SequenceResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, sequence_id):
         """
-        Retrieve given sequence.
+        Get sequence
         ---
         tags:
         - Shots
+        description: Get a sequence by id.
         parameters:
           - in: path
             name: sequence_id
@@ -1199,7 +2173,27 @@ class SequenceResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Given sequence
+                description: Sequence found and returned
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SQ01
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        parent_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         sequence = shots_service.get_full_sequence(sequence_id)
         user_service.check_project_access(sequence["project_id"])
@@ -1208,10 +2202,12 @@ class SequenceResource(Resource, ArgsMixin):
     @jwt_required()
     def delete(self, sequence_id):
         """
-        Delete given sequence.
+        Delete sequence
         ---
         tags:
         - Shots
+        description: Delete a sequence by id. Requires manager access or
+          ownership.
         parameters:
           - in: path
             name: sequence_id
@@ -1221,7 +2217,7 @@ class SequenceResource(Resource, ArgsMixin):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             204:
-                description: Given sequence deleted
+                description: Sequence deleted
         """
         force = self.get_force()
         sequence = shots_service.get_sequence(sequence_id)
@@ -1237,11 +2233,12 @@ class SequencesResource(Resource):
     @jwt_required()
     def get(self):
         """
-        Retrieve all sequence entries.
+        Get sequences
         ---
         tags:
         - Shots
-        description: Filters can be specified in the query string.
+        description: Get sequences with optional filters. Use episode_id to
+          filter by episode.
         parameters:
           - in: query
             name: episode_id
@@ -1252,6 +2249,28 @@ class SequencesResource(Resource):
         responses:
             200:
                 description: All sequence entries
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SQ01
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         criterions = query.get_query_criterions_from_request(request)
         if "episode_id" in criterions:
@@ -1267,11 +2286,12 @@ class SequenceShotsResource(Resource):
     @jwt_required()
     def get(self, sequence_id):
         """
-        Retrieve all shot entries for a given sequence.
+        Get sequence shots
         ---
         tags:
         - Shots
-        description: Filters can be specified in the query string.
+        description: Get shots for a sequence. Supports filtering using query
+          params.
         parameters:
           - in: path
             name: sequence_id
@@ -1288,6 +2308,28 @@ class SequenceShotsResource(Resource):
         responses:
             200:
                 description: All shot entries for given sequence
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         sequence = shots_service.get_sequence(sequence_id)
         user_service.check_project_access(sequence["project_id"])
@@ -1304,10 +2346,11 @@ class ProjectScenesResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve all scenes related to a given project.
+        Get project scenes
         ---
         tags:
         - Shots
+        description: Get all scenes for a project.
         parameters:
           - in: path
             name: project_id
@@ -1318,6 +2361,28 @@ class ProjectScenesResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All scenes related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SC001
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -1326,10 +2391,12 @@ class ProjectScenesResource(Resource, ArgsMixin):
     @jwt_required()
     def post(self, project_id):
         """
-        Create a scene for given project.
+        Create project scene
         ---
         tags:
         - Shots
+        description: Create a new scene in a project. Provide a name and the
+          related sequence id.
         parameters:
           - in: path
             name: project_id
@@ -1359,6 +2426,26 @@ class ProjectScenesResource(Resource, ArgsMixin):
         responses:
             201:
                 description: Scene created for given project
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SC001
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        parent_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         (sequence_id, name) = self.get_arguments()
         projects_service.get_project(project_id)
@@ -1383,10 +2470,11 @@ class SequenceScenesResource(Resource):
     @jwt_required()
     def get(self, sequence_id):
         """
-        Retrieve all scenes related to a given sequence.
+        Get sequence scenes
         ---
         tags:
         - Shots
+        description: Get scenes that belong to a sequence.
         parameters:
           - in: path
             name: sequence_id
@@ -1397,6 +2485,28 @@ class SequenceScenesResource(Resource):
         responses:
             200:
                 description: All scenes related to given sequence
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SC010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          parent_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
         """
         sequence = shots_service.get_sequence(sequence_id)
         user_service.check_project_access(sequence["project_id"])
@@ -1407,10 +2517,11 @@ class SceneTaskTypesResource(Resource):
     @jwt_required()
     def get(self, scene_id):
         """
-        Retrieve all task types related to a given scene.
+        Get scene task types
         ---
         tags:
         - Shots
+        description: Get task types for a scene.
         parameters:
           - in: path
             name: scene_id
@@ -1421,6 +2532,20 @@ class SceneTaskTypesResource(Resource):
         responses:
             200:
                 description: All task types related to given scene
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: Animation
         """
         scene = shots_service.get_scene(scene_id)
         user_service.check_project_access(scene["project_id"])
@@ -1432,10 +2557,11 @@ class SceneTasksResource(Resource):
     @jwt_required()
     def get(self, scene_id):
         """
-        Retrieve all tasks related to a given scene.
+        Get scene tasks
         ---
         tags:
         - Shots
+        description: Get tasks for a scene.
         parameters:
           - in: path
             name: scene_id
@@ -1446,6 +2572,36 @@ class SceneTasksResource(Resource):
         responses:
             200:
                 description: All tasks related to given scene
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SC001 Layout
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: e24a6ea4-ce75-4665-a070-57453082c25
         """
         scene = shots_service.get_scene(scene_id)
         user_service.check_entity_access(scene["id"])
@@ -1456,10 +2612,11 @@ class SceneShotsResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, scene_id):
         """
-        Retrieve all shots that come from given scene.
+        Get scene shots
         ---
         tags:
         - Shots
+        description: Get shots that come from a scene.
         parameters:
           - in: path
             name: scene_id
@@ -1470,6 +2627,24 @@ class SceneShotsResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All shots that come from given scene
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
         """
         scene = shots_service.get_scene(scene_id)
         user_service.check_entity_access(scene["id"])
@@ -1478,10 +2653,11 @@ class SceneShotsResource(Resource, ArgsMixin):
     @jwt_required()
     def post(self, scene_id):
         """
-        Mark given scene as source of given shot.
+        Link shot to scene
         ---
         tags:
         - Shots
+        description: Link a shot to a scene as its source.
         parameters:
           - in: path
             name: scene_id
@@ -1504,8 +2680,21 @@ class SceneShotsResource(Resource, ArgsMixin):
                     required: true
                     example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
-            200:
-                description: Given scene marked as source of given shot
+            201:
+                description: Scene marked as source of shot
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        scene_id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        shot_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
         """
         args = self.get_args([("shot_id", None, True)])
 
@@ -1549,16 +2738,18 @@ class RemoveShotFromSceneResource(Resource):
 
 class ShotVersionsResource(Resource):
     """
-    Retrieve data versions of given shot.
+    Get shot versions
     """
 
     @jwt_required()
     def get(self, shot_id):
         """
-        Retrieve data versions of given shot.
+        Get shot versions
         ---
         tags:
         - Shots
+        description: Get data versions of a shot. Use this to inspect version
+          history.
         parameters:
           - in: path
             name: shot_id
@@ -1567,8 +2758,23 @@ class ShotVersionsResource(Resource):
             format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
-            204:
+            200:
                 description: Data versions of given shot
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          created_at:
+                            type: string
+                            format: date-time
+                            example: "2024-01-15T10:30:00Z"
         """
         shot = shots_service.get_shot(shot_id)
         user_service.check_project_access(shot["project_id"])
@@ -1577,17 +2783,16 @@ class ShotVersionsResource(Resource):
 
 
 class ProjectQuotasResource(Resource, ArgsMixin):
-    """
-    Retrieve quotas statistics for shots
-    """
 
     @jwt_required()
     def get(self, project_id, task_type_id):
         """
-        Retrieve quotas statistics for shots.
+        Get project quotas
         ---
         tags:
         - Shots
+        description: Get quotas statistics for a project and task type. Supports
+          weighted and raw modes with optional feedback filtering.
         parameters:
           - in: path
             name: project_id
@@ -1616,6 +2821,21 @@ class ProjectQuotasResource(Resource, ArgsMixin):
         responses:
             200:
                 description: Quotas statistics for shots
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      additionalProperties:
+                        type: object
+                        properties:
+                          count:
+                            type: integer
+                            example: 42
+                          frames:
+                            type: integer
+                            example: 1200
+            400:
+                description: Invalid count_mode or parameter
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -1658,10 +2878,12 @@ class ProjectPersonQuotasResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self, project_id, person_id):
         """
-        Retrieve quotas statistics for shots.
+        Get project person quotas
         ---
         tags:
         - Shots
+        description: Get quotas statistics for a person in a project. Supports
+          weighted and raw modes with optional feedback filtering.
         parameters:
           - in: path
             name: project_id
@@ -1690,6 +2912,21 @@ class ProjectPersonQuotasResource(Resource, ArgsMixin):
         responses:
             200:
                 description: Quotas statistics for shots
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      additionalProperties:
+                        type: object
+                        properties:
+                          count:
+                            type: integer
+                            example: 15
+                          frames:
+                            type: integer
+                            example: 360
+            400:
+                description: Invalid count_mode or parameter
         """
         projects_service.get_project(project_id)
         if (
@@ -1737,10 +2974,13 @@ class SetShotsFramesResource(Resource, ArgsMixin):
     @jwt_required()
     def post(self, project_id, task_type_id):
         """
-        Set frames for given shots.
+        Set shots frames
         ---
         tags:
         - Shots
+        description: Set number of frames on shots based on latest preview
+          files for a task type. Optionally scope by episode via query
+          param.
         requestBody:
           required: true
           content:
@@ -1766,6 +3006,16 @@ class SetShotsFramesResource(Resource, ArgsMixin):
         responses:
             200:
                 description: Frames set for given shots
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        updated:
+                          type: integer
+                          example: 12
+            400:
+                description: Invalid ids or parameters
         """
         user_service.check_manager_project_access(project_id)
         if not fields.is_valid_id(task_type_id) or not fields.is_valid_id(