diff --git a/API_documentation/v3/_compiled.yaml b/API_documentation/v3/_compiled.yaml
index 1708095191..265db0d2b6 100644
--- a/API_documentation/v3/_compiled.yaml
+++ b/API_documentation/v3/_compiled.yaml
@@ -10,47 +10,10 @@ info:
   license:
     name: GNU GPL V3
     url: 'https://www.gnu.org/licenses/gpl-3.0.en.html'
-components:
-  parameters:
-    offsetParam:
-      name: offset
-      in: query
-      description: offset in records count
-      required: false
-      schema:
-        type: integer
-        minimum: 0
-        default: 0
-    limitParam:
-      name: limit
-      in: query
-      description: number of results
-      required: false
-      schema:
-        type: integer
-        minimum: 1
-        maximum: 100
-        default: 10
-    sbas_id:
-      name: sbas_id
-      in: path
-      description: ID of the databox
-      required: true
-      schema:
-        type: integer
-    record_id:
-      name: record_id
-      in: path
-      description: ID of the record
-      required: true
-      schema:
-        $ref: '#/components/parameters/sbas_id/schema'
 paths:
   /me:
     get:
-      description: blabla
-      servers:
-        - url: 'https://alpha.preprod.alchemyasp.com/api/v1'
+      description: todo
       responses:
         '200':
           description: successful operation
@@ -63,7 +26,42 @@ paths:
       description: |
         Fulltext search for records or stories.
 
-        - pagination: use (offset/limit) OR (page/per_page)
+        ## About pagination
+
+        * offset / limit
+
+            offset starts at 0, the unit is "record"
+        * page / per_page
+
+            the first page is 1, per_page is the number of "records" per page.
+
+        so (page=4 ; per_page=5) <===> (offset=15 ; limit=5)
+
+        use (offset/limit) __OR__ (page/per_page)
+
+        ## About "story_children_limit"
+
+        This parameter asks __for each story in the resultset__ to get the __N first__ children (records) of the story.
+
+        example with __N=5__ :
+
+        * If a story contains __3__ children, the story will expose :
+            * children_offset = 0 (always 0 since only first children are returned
+            * children_limit = 5 (copy of the story_children_limit parameter)
+            * children_count = 3 (number or children returned)
+            * children_total = 3 (total number of children in the story)
+
+        * If a story contains __7__ children, the story will expose :
+            * children_offset = 0 (always 0 since only first children are returned
+            * children_limit = 5 (copy of the story_children_limit parameter)
+            * children_count = 5 (number or children returned)
+            * children_total = 7 (total number of children in the story)
+
+        ## About "include(s)"
+
+        To get smaller / faster response, facets and stories children are ommited by default.
+
+        Add _include_ parameters to get those if needed.
       parameters:
         - name: query
           in: query
@@ -83,7 +81,9 @@ paths:
               - 1
             default: 0
           description: |
-            * `0` - search for records * `1` - search for stories
+            search for records or stories
+              * `0` - search for records
+              * `1` - search for stories
         - name: page
           in: query
           description: 'page number, from 1. Use along with "per_page"'
@@ -184,28 +184,7 @@ paths:
                           stories:
                             type: array
                             items:
-                              allOf:
-                                - $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response/allOf/0'
-                                - type: object
-                                  properties:
-                                    children_offset:
-                                      type: integer
-                                      description: Children pagination offset ; Always 0
-                                    children_limit:
-                                      type: integer
-                                      description: Children pagination limit ; Equal to "story_children_limit" passed in request
-                                    children_count:
-                                      type: integer
-                                      description: 'Number of children in "children" array ; [0...limit]'
-                                    children_total:
-                                      type: integer
-                                      description: Total number of -visibles for user- children in this story
-                                    children:
-                                      type: array
-                                      items:
-                                        type: object
-                                        items:
-                                          $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response'
+                              $ref: '#/paths/~1stories~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/responses/200/content/application~1json/schema/properties/response'
                           records:
                             type: array
                             items:
@@ -244,68 +223,24 @@ paths:
                                     description: Formulated query to search items matching this facet
                                     example: 'database:db_demo'
         default:
-          description: Any (other) error
+          description: Any other error
   /searchraw:
     post:
       tags:
         - searchraw
       description: |
-        Fulltext search for records or stories; Returns raw es
-        - pagination: use (offset/limit) OR (page/per_page)
+        Fulltext search for records or stories; Returns __raw es documents__
+
+        Stories children are not returned, use route _stories/.../.../children_
+
+        see pagination description in route _search_
       parameters:
-        - name: query
-          in: query
-          description: Fulltext query (<empty> = search all)
-          required: false
-          schema:
-            type: string
-            example: dogs OR cats
-            default: ''
-        - name: search_type
-          in: query
-          required: false
-          schema:
-            type: integer
-            enum:
-              - 0
-              - 1
-            default: 0
-          description: |
-            search for records or stories
-              * `0` - search for records
-              * `1` - search for stories
-        - name: page
-          in: query
-          description: 'page number, from 1. Use along with "per_page"'
-          required: false
-          schema:
-            type: integer
-            minimum: 1
-            default: 1
-        - name: per_page
-          in: query
-          description: number of results per page. Use along with "page"
-          required: false
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 100
-            default: 10
-        - name: offset
-          in: query
-          description: 'offset in records count, from 0. Use along with "limit"'
-          required: false
-          schema:
-            type: integer
-            minimum: 0
-        - name: limit
-          in: query
-          description: number of results. Use along with "offset"
-          required: false
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 100
+        - $ref: '#/paths/~1search/post/parameters/0'
+        - $ref: '#/paths/~1search/post/parameters/1'
+        - $ref: '#/paths/~1search/post/parameters/2'
+        - $ref: '#/paths/~1search/post/parameters/3'
+        - $ref: '#/paths/~1search/post/parameters/4'
+        - $ref: '#/paths/~1search/post/parameters/5'
       responses:
         '200':
           description: ok
@@ -349,9 +284,9 @@ paths:
                               type: object
                               properties:
                                 record_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 collection_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 uuid:
                                   type: string
                                   example: dcee40ea-ee26-4d8b-b0c2-d61305b03bc0
@@ -378,7 +313,7 @@ paths:
                                   format: date-time
                                   example: '2021-01-01 15:30:00'
                                 coll_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 collection_name:
                                   type: string
                                   example: collection de test
@@ -392,9 +327,9 @@ paths:
                                   type: integer
                                   example: 5618218
                                 base_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 databox_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 databox_name:
                                   type: string
                                   example: db_databox1
@@ -503,11 +438,22 @@ paths:
       tags:
         - record
       summary: Find record by sbas_id and record_id
-      description: Returns a single record
+      description: |
+        Returns a single record, which can be a real record or a story (check `is_story`)
       operationId: getRecordById
       parameters:
-        - $ref: '#/components/parameters/sbas_id'
-        - $ref: '#/components/parameters/record_id'
+        - name: sbas_id
+          in: path
+          description: ID of the databox
+          required: true
+          schema:
+            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
+        - name: record_id
+          in: path
+          description: ID of the record
+          required: true
+          schema:
+            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
       responses:
         '200':
           description: ok
@@ -545,7 +491,13 @@ paths:
           description: ID of the base
           required: true
           schema:
-            $ref: '#/components/parameters/sbas_id/schema'
+            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
+        - name: base_id
+          in: path
+          description: ID of the base
+          required: true
+          schema:
+            type: integer
       requestBody:
         content:
           multipart/form-data:
@@ -574,7 +526,7 @@ paths:
                           field_name:
                             type: string
                           meta_struct_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           action:
                             type: string
                             enum:
@@ -607,15 +559,30 @@ paths:
                 type: object
                 properties:
                   meta:
-                    $ref: '#/paths/~1search/post/responses/200/content/application~1json/schema/properties/meta'
+                    type: object
+                    properties:
+                      api_version:
+                        type: string
+                      request:
+                        type: string
+                      response_time:
+                        type: string
+                        format: date-time
+                      http_code:
+                        type: integer
+                        format: int32
+                      error_type:
+                        type: string
+                      error_message:
+                        type: string
                   response:
                     allOf:
                       - type: object
                         properties:
                           databox_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           record_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           title:
                             type: string
                           original_name:
@@ -627,9 +594,9 @@ paths:
                             type: string
                             format: date-time
                           collection_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           base_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           thumbnail:
                             type: object
                             properties:
@@ -642,7 +609,7 @@ paths:
                                     type: string
                                     format: date-time
                                   id:
-                                    $ref: '#/components/parameters/sbas_id/schema'
+                                    $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                   is_activated:
                                     type: boolean
                                   label:
@@ -1059,18 +1026,8 @@ paths:
         ```
       operationId: patchRecord
       parameters:
-        - name: sbas_id
-          in: path
-          description: ID of the sbas
-          required: true
-          schema:
-            $ref: '#/components/parameters/sbas_id/schema'
-        - name: record_id
-          in: path
-          description: ID of the record
-          required: true
-          schema:
-            $ref: '#/components/parameters/sbas_id/schema'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/0'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/1'
       requestBody:
         content:
           application/json:
@@ -1086,6 +1043,60 @@ paths:
                 $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema'
         default:
           $ref: '#/paths/~1search/post/responses/default'
+  '/stories/{sbas_id}/{record_id}':
+    get:
+      tags:
+        - story
+      summary: Find a story (record) by sbas_id and record_id
+      description: |
+        Returns a single story
+
+        This is the __same__ parameters / result as _/records/..._, except that here the record __must__ be a story else 404 is returned
+      operationId: getRecordById
+      parameters:
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/0'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/1'
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  meta:
+                    $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/meta'
+                  response:
+                    allOf:
+                      - $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response/allOf/0'
+                      - type: object
+                        properties:
+                          children_offset:
+                            type: integer
+                            description: Children pagination offset ; Always 0
+                            example: 0
+                          children_limit:
+                            type: integer
+                            description: Children pagination limit ; Equal to "story_children_limit" passed in request
+                            example: 10
+                          children_count:
+                            type: integer
+                            description: 'Number of children in "children" array ; [0...limit]'
+                            example: 5
+                          children_total:
+                            type: integer
+                            description: Total number of __visibles for user__ children in this story
+                            example: 5
+                          children:
+                            type: array
+                            items:
+                              type: object
+                              items:
+                                $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response'
+        '404':
+          description: Story not found (
+        default:
+          $ref: '#/paths/~1search/post/responses/default'
   '/stories/{sbas_id}/{record_id}/children':
     get:
       tags:
@@ -1094,8 +1105,8 @@ paths:
       description: Returns children of a story
       operationId: getStoryChildren
       parameters:
-        - $ref: '#/components/parameters/sbas_id'
-        - $ref: '#/components/parameters/record_id'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/0'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/1'
         - name: page
           in: query
           description: page number (default 1)
@@ -1117,7 +1128,7 @@ paths:
                 type: object
                 properties:
                   meta:
-                    $ref: '#/paths/~1search/post/responses/200/content/application~1json/schema/properties/meta'
+                    $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/meta'
                   response:
                     type: array
                     items:
diff --git a/API_documentation/v3/api.yaml b/API_documentation/v3/api.yaml
index 13d3083ca6..f45197266a 100644
--- a/API_documentation/v3/api.yaml
+++ b/API_documentation/v3/api.yaml
@@ -1,17 +1,17 @@
 openapi: 3.0.0
 info:
-    description: >
-        This is the documentation of Phraseanet API (v3)
-#        [https://alpha.preprod.alchemyasp.com/api/v3](https://alpha.preprod.alchemyasp.com/api/v3).
-    version: "1.0.0-oas3"
-    title: Phraseanet API
-    # todo : fix url
-    termsOfService: 'http://phraseanet.com/terms/'
-    contact:
-        email: support@alchemy.fr
-    license:
-        name: GNU GPL V3
-        url: 'https://www.gnu.org/licenses/gpl-3.0.en.html'
+  description: >
+    This is the documentation of Phraseanet API (v3)
+  #        [https://alpha.preprod.alchemyasp.com/api/v3](https://alpha.preprod.alchemyasp.com/api/v3).
+  version: "1.0.0-oas3"
+  title: Phraseanet API
+  # todo : fix url
+  termsOfService: 'http://phraseanet.com/terms/'
+  contact:
+    email: support@alchemy.fr
+  license:
+    name: GNU GPL V3
+    url: 'https://www.gnu.org/licenses/gpl-3.0.en.html'
 #servers:
 #    - url: https://alpha.preprod.alchemyasp.com/api/v3
 #      description: Phraseanet alpha (dev)
@@ -20,7 +20,7 @@ info:
 #security:
 #    - api_key: []
 #    - oAuth2Password: []
-components:
+#components:
 #    securitySchemes:
 #        api_key:
 #            type: apiKey
@@ -32,707 +32,636 @@ components:
 #            flows:
 #                password:   # <-- OAuth flow(authorizationCode, implicit, password or clientCredentials)
 #                    tokenUrl: azea
-    parameters:
-        offsetParam:
-            name: offset
-            in: query
-            description: offset in records count
-            required: false
-            schema:
-                type: integer
-                minimum: 0
-                default: 0
-        limitParam:
-            name: limit
-            in: query
-            description: number of results
-            required: false
-            schema:
-                type: integer
-                minimum: 1
-                maximum: 100
-                default: 10
-        sbas_id:
-            name: sbas_id
-            in: path
-            description: ID of the databox
-            required: true
-            schema:
-                $ref: schemas.yaml#/ID
-        record_id:
-            name: record_id
-            in: path
-            description: ID of the record
-            required: true
-            schema:
-                $ref: schemas.yaml#/ID
+
 paths:
-    '/me':
-        get:
-            description: 'blabla'
-            servers:
-                - url: 'https://alpha.preprod.alchemyasp.com/api/v1'
-            responses:
-                200:
-                    description: successful operation
-                default:
-                    description: Any error
+  '/me':
+    get:
+      description: 'todo'
+      responses:
+        200:
+          description: successful operation
+        default:
+          description: Any error
 
-    # ---------------- search ----------------
-    '/search':
-        post:
-            tags:
-                - search
-            description: |
-                Fulltext search for records or stories.
+  # ---------------- search ----------------
+  '/search':
+    post:
+      tags:
+        - search
+      description: |
+        Fulltext search for records or stories.
 
-                - pagination: use (offset/limit) OR (page/per_page)
-            parameters:
-                - name: query
-                  in: query
-                  description: 'Fulltext query (<empty> = search all)'
-                  required: false
-                  schema:
-                      type: string
-                      example: 'dogs OR cats'
-                      default: ''
-                - name: search_type
-                  in: query
-                  required: false
-                  schema:
-                      type: integer
-                      enum: [0,1]
-                      default: 0
-                  description: >
-                       * `0` - search for records
-                       * `1` - search for stories
-                - name: page
-                  in: query
-                  description: page number, from 1. Use along with "per_page"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 1
-                      default: 1
-                - name: per_page
-                  in: query
-                  description: number of results per page. Use along with "page"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 1
-                      maximum: 100
-                      default: 10
-                - name: offset
-                  in: query
-                  description: offset in records count, from 0. Use along with "limit"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 0
-                      # default: 0
-                - name: limit
-                  in: query
-                  description: number of results. Use along with "offset"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 1
-                      maximum: 100
-                      # default: 10
-                - name: story_children_limit
-                  in: query
-                  description: For each story in result, include N children
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 0
-                      maximum: 10
-                      default: '0'
-                - name: include
-                  in: query
-                  description: Suplemental elements to be included in response
-                  required: false
-                  schema:
-                      type: array
-                      uniqueItems: false
-                      items:
-                          type: string
-                          enum:
-                              - facets
-                              - result.stories.children
-            responses:
-                200:
-                    description: ok
-                    content:
-                        application/json:
-                            schema:
-                                $ref: 'schemas.yaml#/ApiResponse_search'
-                default:
-                    $ref: 'responses.yaml#/error_response'
-    # ---------------- searchraw ----------------
-    '/searchraw':
-        post:
-            tags:
-                - searchraw
-            description: >
-                Fulltext search for records or stories; Returns raw es
+        ## About pagination
 
-                - pagination: use (offset/limit) OR (page/per_page)
-            parameters:
-                - name: query
-                  in: query
-                  description: 'Fulltext query (<empty> = search all)'
-                  required: false
-                  schema:
-                      type: string
-                      example: 'dogs OR cats'
-                      default: ''
-                - name: search_type
-                  in: query
-                  required: false
-                  schema:
-                      type: integer
-                      enum: [0,1]
-                      default: 0
-                  description: >
-                      search for records or stories
-                        * `0` - search for records
-                        * `1` - search for stories
-                - name: page
-                  in: query
-                  description: page number, from 1. Use along with "per_page"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 1
-                      default: 1
-                - name: per_page
-                  in: query
-                  description: number of results per page. Use along with "page"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 1
-                      maximum: 100
-                      default: 10
-                - name: offset
-                  in: query
-                  description: offset in records count, from 0. Use along with "limit"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 0
-                      # default: 0
-                - name: limit
-                  in: query
-                  description: number of results. Use along with "offset"
-                  required: false
-                  schema:
-                      type: integer
-                      minimum: 1
-                      maximum: 100
-                      # default: 10
-            responses:
-                200:
-                    description: ok
-                    content:
-                        application/json:
-                            schema:
-                                $ref: 'schemas.yaml#/ApiResponse_searchraw'
-                default:
-                    $ref: 'responses.yaml#/error_response'
+        * offset / limit
 
-# ------------ record -----------
-    '/records/{sbas_id}/{record_id}':
-        get:
-            tags:
-                - record
-            summary: Find record by sbas_id and record_id
-            description: Returns a single record
-            operationId: getRecordById
-            parameters:
-                - $ref: '#/components/parameters/sbas_id'
-                - $ref: '#/components/parameters/record_id'
-            responses:
-                200:
-                    description: ok
-                    content:
-                        application/json:
-                            schema:
-                                $ref: schemas.yaml#/ApiResponse_record
-                404:
-                    description: Record not found
-                default:
-                    $ref: 'responses.yaml#/error_response'
+            offset starts at 0, the unit is "record"
+        * page / per_page
 
-    '/records/{base_id}':
-        post:
-            tags:
-                - record
-            summary: Creates a record
-            description: |
-                Creates a single record, including document and/or data.
+            the first page is 1, per_page is the number of "records" per page.
 
-                ### To create a record __with__ a file (document)
+        so (page=4 ; per_page=5) <===> (offset=15 ; limit=5)
 
-                _Since multipart is required to pass a file, json data must be passed as a part named "body"_
+        use (offset/limit) __OR__ (page/per_page)
 
-                ### To create a record __without__ file
+        ## About "story_children_limit"
 
-                _Since no file is passed, data can be passed as plain body_
+        This parameter asks __for each story in the resultset__ to get the __N first__ children (records) of the story.
 
-                ### metadata / status-bits setting
+        example with __N=5__ :
 
-                see "PATCH" method for examples, apply only relevant "set" operation on just created record with empty data.
+        * If a story contains __3__ children, the story will expose :
+            * children_offset = 0 (always 0 since only first children are returned
+            * children_limit = 5 (copy of the story_children_limit parameter)
+            * children_count = 3 (number or children returned)
+            * children_total = 3 (total number of children in the story)
 
-            operationId: createRecord
-            parameters:
-                - name: base_id
-                  in: path
-                  description: ID of the base
-                  required: true
-                  schema:
-                      $ref: schemas.yaml#/ID
-            requestBody:
-                content:
-                    multipart/form-data:
-                        schema:
-                            description: to create a record __with__ a file (document)
-                            type: object
-                            properties:
-                                body:
-                                    $ref: schemas.yaml#/RecordPatch
-                                file:
-                                    description : 'uploaded file'
-                                    type: string
-                                    format: binary
-                    application/json:
-                        schema:
-                            description: To create a record __without__ file
-                            allOf:
-                                - $ref: schemas.yaml#/RecordPatch
-            responses:
-                200:
-                    description: ok
-                    content:
-                        application/json:
-                            schema:
-                                $ref: schemas.yaml#/ApiResponse_record
-                default:
-                    $ref: 'responses.yaml#/error_response'
-            # security:
-            #   - api_key: []
+        * If a story contains __7__ children, the story will expose :
+            * children_offset = 0 (always 0 since only first children are returned
+            * children_limit = 5 (copy of the story_children_limit parameter)
+            * children_count = 5 (number or children returned)
+            * children_total = 7 (total number of children in the story)
 
-    '/records/{sbas_id}/{record_id}/setmetadatas':
-        patch:
-            tags:
-                - record
-            summary: Set or change metadata and/or status-bits of a record
-            description: |
-                Set or change metadata and/or status-bits of a record.
+        ## About "include(s)"
 
-                Data is sent as json in the BODY of the request.
+        To get smaller / faster response, facets and stories children are ommited by default.
 
-                * metadatas is an array of simple “actions” that are applied in the same order as defined into json.
-                * field can be specified by meta_struct_id or by name
-                * field value (when relevant) can be specified by meta_id or by actual value
-                * method to match a value can be (strict | ignore-case | regexp); default is “ignore-case”
-                * to act on multi-values we must set an “action” (set | add | delete | replace); default is “set”
-                * default action “set” and special value (null, arrays) allow to write simplified actions
-                * the “replace” action is useful to set/add values only if a value already exists
+        Add _include_ parameters to get those if needed.
 
-                # Body examples :
+      parameters:
+        - $ref: 'parameters.yaml#/query'
+        - $ref: 'parameters.yaml#/search_type'
+        - $ref: 'parameters.yaml#/page'
+        - $ref: 'parameters.yaml#/per_page'
+        - $ref: 'parameters.yaml#/offset'
+        - $ref: 'parameters.yaml#/limit'
+        - name: story_children_limit
+          in: query
+          description: For each story in result, include N children
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            maximum: 10
+            default: '0'
+        - name: include
+          in: query
+          description: Suplemental elements to be included in response
+          required: false
+          schema:
+            type: array
+            uniqueItems: false
+            items:
+              type: string
+              enum:
+                - facets
+                - result.stories.children
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'search.yaml#/ApiResponse_search'
+        default:
+          $ref: 'responses.yaml#/error_response'
 
-                ## mono-valued fields
+  # ---------------- searchraw ----------------
+  '/searchraw':
+    post:
+      tags:
+        - searchraw
+      description: |
+        Fulltext search for records or stories; Returns __raw es documents__
 
-                set a mono-value field by its meta_struct_id
+        Stories children are not returned, use route _stories/.../.../children_
 
-                ```json
+        see pagination description in route _search_
+      parameters:
+        - $ref: 'parameters.yaml#/query'
+        - $ref: 'parameters.yaml#/search_type'
+        - $ref: 'parameters.yaml#/page'
+        - $ref: 'parameters.yaml#/per_page'
+        - $ref: 'parameters.yaml#/offset'
+        - $ref: 'parameters.yaml#/limit'
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'searchraw.yaml#/ApiResponse_searchraw'
+        default:
+          $ref: 'responses.yaml#/error_response'
+
+  # ------------ record -----------
+  '/records/{sbas_id}/{record_id}':
+    get:
+      tags:
+        - record
+      summary: Find record by sbas_id and record_id
+      description: |
+        Returns a single record, which can be a real record or a story (check `is_story`)
+      operationId: getRecordById
+      parameters:
+        - $ref: 'parameters.yaml#/sbas_id'
+        - $ref: 'parameters.yaml#/record_id'
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: schemas.yaml#/ApiResponse_record
+        404:
+          description: Record not found
+        default:
+          $ref: 'responses.yaml#/error_response'
+
+  '/records/{base_id}':
+    post:
+      tags:
+        - record
+      summary: Creates a record
+      description: |
+        Creates a single record, including document and/or data.
+
+        ### To create a record __with__ a file (document)
+
+        _Since multipart is required to pass a file, json data must be passed as a part named "body"_
+
+        ### To create a record __without__ file
+
+        _Since no file is passed, data can be passed as plain body_
+
+        ### metadata / status-bits setting
+
+        see "PATCH" method for examples, apply only relevant "set" operation on just created record with empty data.
+
+      operationId: createRecord
+      parameters:
+        - $ref: 'parameters.yaml#/base_id'
+        - name: base_id
+          in: path
+          description: ID of the base
+          required: true
+          schema:
+            $ref: common.yaml#/ID
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              description: to create a record __with__ a file (document)
+              type: object
+              properties:
+                body:
+                  $ref: schemas.yaml#/RecordPatch
+                file:
+                  description : 'uploaded file'
+                  type: string
+                  format: binary
+          application/json:
+            schema:
+              description: To create a record __without__ file
+              allOf:
+                - $ref: schemas.yaml#/RecordPatch
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: schemas.yaml#/ApiResponse_record
+        default:
+          $ref: 'responses.yaml#/error_response'
+      # security:
+      #   - api_key: []
+
+  '/records/{sbas_id}/{record_id}/setmetadatas':
+    patch:
+      tags:
+        - record
+      summary: Set or change metadata and/or status-bits of a record
+      description: |
+        Set or change metadata and/or status-bits of a record.
+
+        Data is sent as json in the BODY of the request.
+
+        * metadatas is an array of simple “actions” that are applied in the same order as defined into json.
+        * field can be specified by meta_struct_id or by name
+        * field value (when relevant) can be specified by meta_id or by actual value
+        * method to match a value can be (strict | ignore-case | regexp); default is “ignore-case”
+        * to act on multi-values we must set an “action” (set | add | delete | replace); default is “set”
+        * default action “set” and special value (null, arrays) allow to write simplified actions
+        * the “replace” action is useful to set/add values only if a value already exists
+
+        # Body examples :
+
+        ## mono-valued fields
+
+        set a mono-value field by its meta_struct_id
+
+        ```json
+        {
+            "metadatas": [
                 {
-                    "metadatas": [
-                        {
-                            "meta_struct_id": 1,
-                            "action": "set",
-                            "value": "A pretty string"
-                        }
+                    "meta_struct_id": 1,
+                    "action": "set",
+                    "value": "A pretty string"
+                }
+            ]
+        }
+        ```
+
+
+        same thing (because default action is “set”), by field name
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Author",
+                    "value": "John Doe"
+                }
+            ]
+        }
+        ```
+
+        delete a mono-valued field
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Copyright",
+                    "action": "delete"
+                }
+            ]
+        }
+        ```
+
+        same thing
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Copyright",
+                    "value": null
+                }
+            ]
+        }
+        ```
+
+        ## multi-valued
+
+        replace a keyword __if we know its meta-id__
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "meta_id": 678,
+                    "value": "Dog"
+                }
+            ]
+        }
+        ```
+
+        delete a specific keyword by its meta-id (we could also set action : “delete”, omit value, …)
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "meta_id": 345,
+                    "value": null
+                }
+            ]
+        }
+        ```
+
+        delete a specific keyword by its value. Since we must pass the value (not null), we must set the action “delete”
+
+        _nb_ : the default matching method is “ignore-case” so we can write the actual value all small letters
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "action": "delete",
+                    "value": "doggy"
+                }
+            ]
+        }
+        ```
+
+        delete __all Keywords__
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "value": null
+                }
+            ]
+        }
+        ```
+
+        add a keyword
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "action": "add",
+                    "value": "Cat"
+                }
+            ]
+        }
+        ```
+
+        replace all keywords by new ones
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "value": null
+                },
+                {
+                    "field_name": "Keywords",
+                    "action": "add",
+                    "value": "Cat"
+                },
+                {
+                    "field_name": "Keywords",
+                    "action": "add",
+                    "value": "Dog"
+                }
+            ]
+        }
+        ```
+
+        same thing using an array
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "value": [
+                            "Dog",
+                            "Cat",
                     ]
                 }
-                ```
+            ]
+        }
+        ```
 
+        simplification of multiple same actions with arrays as value
 
-                same thing (because default action is “set”), by field name
-
-                ```
+        ```
+        {
+            "metadatas": [
                 {
-                    "metadatas": [
-                        {
-                            "field_name": "Author",
-                            "value": "John Doe"
-                        }
+                    "field_name": "Keywords",
+                    "action": "delete",
+                    "value": [
+                            "cop",
+                            "bobby",
+                            "pig",
+                            "nicks"
+                    ]
+                },
+                {
+                    "field_name": "Keywords",
+                    "action": "add",
+                    "value": [
+                            "Policeman",
+                            "Arrest"
                     ]
                 }
-                ```
+            ]
+        }
+        ```
 
-                delete a mono-valued field
+        replacing a keyword by value can be 2 actions if we know that the bad value exists…
 
-                ```
+        ```
+        {
+            "metadatas": [
                 {
-                    "metadatas": [
-                        {
-                            "field_name": "Copyright",
-                            "action": "delete"
-                        }
+                    "field_name": "Keywords",
+                    "action": "delete",
+                    "value": "cop"
+                },
+                {
+                    "field_name": "Keywords",
+                    "action": "add",
+                    "value": "Policeman"
+                }
+            ]
+        }
+        ```
+
+        replace-if-exists
+
+        …but we can also use the “replace” action if we are not sure
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "action": "replace",
+                    "value": "cop",
+                    "replace_with": "Policeman"
+                }
+            ]
+        }
+        ```
+
+        fix  spelling errors with regexp
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Persons",
+                    "action": "replace",
+                    "match_method": "regexp",
+                    "value": "/joh?nn?[i|y]\w+hall?[i|y]day/\w+in\w([0-9]{4})/i",
+                    "replace_with": "Johnny Halliday in $1"
+                }
+            ]
+        }
+        ```
+
+        add translations for existing keywords (using “replace”)
+
+        _nb_ : multi-values are kept unique so double replacement is not a pb.
+
+        ```
+        {
+            "metadatas": [
+                {
+                    "field_name": "Keywords",
+                    "action": "replace",
+                    "value": "dog",
+                    "replace_with": [
+                            "Dog",
+                            "Chien"
+                    ]
+                },
+                {
+                    "field_name": "Keywords",
+                    "action": "replace",
+                    "value": "chien",
+                    "replace_with": [
+                            "Dog",
+                            "Chien"
                     ]
                 }
-                ```
+            ]
+        }
+        ```
 
-                same thing
+        same thing using regexp
 
-                ```
+        ```
+        {
+            "metadatas": [
                 {
-                    "metadatas": [
-                        {
-                            "field_name": "Copyright",
-                            "value": null
-                        }
+                    "field_name": "Keywords",
+                    "action": "replace",
+                    "value": "/cop|bobby|pig|flic/i",
+                    "match_method": "regexp",
+                    "replace_with": [
+                            "Policeman",
+                            "Policier"
                     ]
                 }
-                ```
+            ]
+        }
+        ```
 
-                ## multi-valued
+        ## Status-bits
 
-                replace a keyword __if we know its meta-id__
+        sb can be changed with the same api.
 
-                ```
+        To not get confused with "names", sb are referenced by bit number only 4…31
+
+        ```
+        {
+            "metadatas": [
+                    ...
+            ],
+            "status": [
                 {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "meta_id": 678,
-                            "value": "Dog"
-                        }
-                    ]
-                }
-                ```
-
-                delete a specific keyword by its meta-id (we could also set action : “delete”, omit value, …)
-
-                ```
+                    "bit": 4,
+                    "state": true
+                },
                 {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "meta_id": 345,
-                            "value": null
-                        }
-                    ]
-                }
-                ```
-
-                delete a specific keyword by its value. Since we must pass the value (not null), we must set the action “delete”
-
-                _nb_ : the default matching method is “ignore-case” so we can write the actual value all small letters
-
-                ```
+                    "bit": 5,
+                    "state": false
+                },
                 {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "action": "delete",
-                            "value": "doggy"
-                        }
-                    ]
-                }
-                ```
-
-                delete __all Keywords__
-
-                ```
+                    "bit": 6,
+                    "state": false
+                },
                 {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "value": null
-                        }
-                    ]
+                    "bit": 7,
+                    "state": false
                 }
-                ```
+            ]
+        }
+        ```
 
-                add a keyword
+      operationId: patchRecord
+      parameters:
+        - $ref: 'parameters.yaml#/sbas_id'
+        - $ref: 'parameters.yaml#/record_id'
 
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "action": "add",
-                            "value": "Cat"
-                        }
-                    ]
-                }
-                ```
+      requestBody:
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: schemas.yaml#/RecordPatch
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: schemas.yaml#/ApiResponse_record
+        default:
+          $ref: 'responses.yaml#/error_response'
 
-                replace all keywords by new ones
+  '/stories/{sbas_id}/{record_id}':
+    get:
+      tags:
+        - story
+      summary: Find a story (record) by sbas_id and record_id
+      description: |
+        Returns a single story
 
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "value": null
-                        },
-                        {
-                            "field_name": "Keywords",
-                            "action": "add",
-                            "value": "Cat"
-                        },
-                        {
-                            "field_name": "Keywords",
-                            "action": "add",
-                            "value": "Dog"
-                        }
-                    ]
-                }
-                ```
+        This is the __same__ parameters / result as _/records/..._, except that here the record __must__ be a story else 404 is returned
 
-                same thing using an array
-
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "value": [
-                                    "Dog",
-                                    "Cat",
-                            ]
-                        }
-                    ]
-                }
-                ```
-
-                simplification of multiple same actions with arrays as value
-
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "action": "delete",
-                            "value": [
-                                    "cop",
-                                    "bobby",
-                                    "pig",
-                                    "nicks"
-                            ]
-                        },
-                        {
-                            "field_name": "Keywords",
-                            "action": "add",
-                            "value": [
-                                    "Policeman",
-                                    "Arrest"
-                            ]
-                        }
-                    ]
-                }
-                ```
-
-                replacing a keyword by value can be 2 actions if we know that the bad value exists…
-
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "action": "delete",
-                            "value": "cop"
-                        },
-                        {
-                            "field_name": "Keywords",
-                            "action": "add",
-                            "value": "Policeman"
-                        }
-                    ]
-                }
-                ```
-
-                replace-if-exists
-
-                …but we can also use the “replace” action if we are not sure
-
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "action": "replace",
-                            "value": "cop",
-                            "replace_with": "Policeman"
-                        }
-                    ]
-                }
-                ```
-
-                fix  spelling errors with regexp
-
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Persons",
-                            "action": "replace",
-                            "match_method": "regexp",
-                            "value": "/joh?nn?[i|y]\w+hall?[i|y]day/\w+in\w([0-9]{4})/i",
-                            "replace_with": "Johnny Halliday in $1"
-                        }
-                    ]
-                }
-                ```
-
-                add translations for existing keywords (using “replace”)
-
-                _nb_ : multi-values are kept unique so double replacement is not a pb.
-
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "action": "replace",
-                            "value": "dog",
-                            "replace_with": [
-                                    "Dog",
-                                    "Chien"
-                            ]
-                        },
-                        {
-                            "field_name": "Keywords",
-                            "action": "replace",
-                            "value": "chien",
-                            "replace_with": [
-                                    "Dog",
-                                    "Chien"
-                            ]
-                        }
-                    ]
-                }
-                ```
-
-                same thing using regexp
-
-                ```
-                {
-                    "metadatas": [
-                        {
-                            "field_name": "Keywords",
-                            "action": "replace",
-                            "value": "/cop|bobby|pig|flic/i",
-                            "match_method": "regexp",
-                            "replace_with": [
-                                    "Policeman",
-                                    "Policier"
-                            ]
-                        }
-                    ]
-                }
-                ```
-
-                ## Status-bits
-
-                sb can be changed with the same api.
-
-                To not get confused with "names", sb are referenced by bit number only 4…31
-
-                ```
-                {
-                    "metadatas": [
-                            ...
-                    ],
-                    "status": [
-                        {
-                            "bit": 4,
-                            "state": true
-                        },
-                        {
-                            "bit": 5,
-                            "state": false
-                        },
-                        {
-                            "bit": 6,
-                            "state": false
-                        },
-                        {
-                            "bit": 7,
-                            "state": false
-                        }
-                    ]
-                }
-                ```
-
-            operationId: patchRecord
-            parameters:
-                - name: sbas_id
-                  in: path
-                  description: ID of the sbas
-                  required: true
-                  schema:
-                      $ref: schemas.yaml#/ID
-                - name: record_id
-                  in: path
-                  description: ID of the record
-                  required: true
-                  schema:
-                      $ref: schemas.yaml#/ID
-
-            requestBody:
-                content:
-                    application/json:
-                        schema:
-                            allOf:
-                                - $ref: schemas.yaml#/RecordPatch
-            responses:
-                200:
-                    description: ok
-                    content:
-                        application/json:
-                            schema:
-                                $ref: schemas.yaml#/ApiResponse_record
-                default:
-                    $ref: 'responses.yaml#/error_response'
+      operationId: getRecordById
+      parameters:
+        - $ref: 'parameters.yaml#/sbas_id'
+        - $ref: 'parameters.yaml#/record_id'
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: schemas.yaml#/ApiResponse_story
+        404:
+          description: Story not found (
+        default:
+          $ref: 'responses.yaml#/error_response'
 
 
-    '/stories/{sbas_id}/{record_id}/children':
-        get:
-            tags:
-                - story
-            summary: Returns uri of each record (child) contained in the story ; Optional pagination
-            description: Returns children of a story
-            operationId: getStoryChildren
-            parameters:
-                - $ref: '#/components/parameters/sbas_id'
-                - $ref: '#/components/parameters/record_id'
-                - name: page
-                  in: query
-                  description: page number (default 1)
-                  required: false
-                  schema:
-                      type: integer
-                - name: per_page
-                  in: query
-                  description: number of children (records uri) per page (default 10)
-                  required: false
-                  schema:
-                      type: integer
-            responses:
-                200:
-                    description: ok
-                    content:
-                        application/json:
-                            schema:
-                                $ref: schemas.yaml#/ApiResponse_RecordsUriArray
-                404:
-                    description: Story (record) not found
-                default:
-                    $ref: 'responses.yaml#/error_response'
+  '/stories/{sbas_id}/{record_id}/children':
+    get:
+      tags:
+        - story
+      summary: Returns uri of each record (child) contained in the story ; Optional pagination
+      description: Returns children of a story
+      operationId: getStoryChildren
+      parameters:
+        - $ref: 'parameters.yaml#/sbas_id'
+        - $ref: 'parameters.yaml#/record_id'
+        - name: page
+          in: query
+          description: page number (default 1)
+          required: false
+          schema:
+            type: integer
+        - name: per_page
+          in: query
+          description: number of children (records uri) per page (default 10)
+          required: false
+          schema:
+            type: integer
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: schemas.yaml#/ApiResponse_RecordsUriArray
+        404:
+          description: Story (record) not found
+        default:
+          $ref: 'responses.yaml#/error_response'
diff --git a/API_documentation/v3/common.yaml b/API_documentation/v3/common.yaml
new file mode 100644
index 0000000000..6a0ce28144
--- /dev/null
+++ b/API_documentation/v3/common.yaml
@@ -0,0 +1,79 @@
+  ApiResponse_meta:
+    type: object
+    properties:
+      api_version:
+        type: string
+      request:
+        type: string
+      response_time:
+        type: string
+        format: date-time
+      http_code:
+        type: integer
+        format: int32
+      error_type:
+        type: string
+      error_message:
+        type: string
+
+  Facet:
+    type: object
+    properties:
+      name:
+        type: string
+        description: 'Unique internal name (=key) for the facet'
+        example: '_base'
+      field:
+        type: string
+        description: 'Source field (from db structure). Can be also virtual field like "database" '
+        example: 'database'
+      values:
+        type: array
+        items:
+          type: object
+          properties:
+            value:
+              type: string
+              description: 'Human readable value for the value'
+              example: 'Demo'
+            raw_value:
+              type: string
+              description: 'Real value, to be used to query'
+              example: 'db_demo'
+            count:
+              type: integer
+              description: 'Number of items matching this value'
+            query:
+              type: string
+              description: 'Formulated query to search items matching this facet'
+              example: 'database:db_demo'
+
+  PermalinkObject:
+    type: object
+    properties:
+      created_on:
+        type: string
+        format: date-time
+      id:
+        $ref: '#/ID'
+      is_activated:
+        type: boolean
+      label:
+        type: string
+      updated_on:
+        type: string
+        format: date-time
+      page_url:
+        type: string
+      download_url:
+        type: string
+      url:
+        type: string
+
+  FacetsArray:
+    type: array
+    items:
+      $ref: '#/Facet'
+
+  ID:
+    type: integer
diff --git a/API_documentation/v3/es.yaml b/API_documentation/v3/es.yaml
new file mode 100644
index 0000000000..0858e5fe9f
--- /dev/null
+++ b/API_documentation/v3/es.yaml
@@ -0,0 +1,175 @@
+ESRecord:
+  description: 'Raw response from es search on "record" index/mapping'
+  type: object
+  properties:
+    _index:
+      type: string
+      description: 'ES index'
+      example:
+        'phraseanet_dxmpcw3y8td68f+h_20201124161735.910647'
+    _type:
+      type: string
+      description: 'Data type'
+      example:
+        'record'
+    _id:
+      type: string
+      description: 'unique id of document (sbas_id + "_" + record_id)'
+      example:
+        '1_555'
+    _version:
+      type: integer
+      description: 'auto-increment at each indexation of the document'
+      example:
+        1
+    _score:
+      type: number
+      description: 'score of the document related to a whole resultset'
+      example:
+        1
+    _source:
+      $ref: '#/ESRecordSource'
+
+ESRecordSource:
+  type: object
+  properties:
+    record_id:
+      $ref: 'common.yaml#/ID'
+    collection_id:
+      $ref: 'common.yaml#/ID'
+    uuid:
+      type: string
+      example:
+        'dcee40ea-ee26-4d8b-b0c2-d61305b03bc0'
+    flags_bitfield:
+      type: integer
+    sha256:
+      type: string
+      example:
+        '7fad283de349b903c850548cda65cf2d86d24c4e3856cdc2b97e47430494b8c8'
+    original_name:
+      type: string
+      example:
+        '1134340545.jpg'
+    mime:
+      type: string
+      example:
+        'image/jpeg'
+    type:
+      type: string
+      example:
+        'image'
+    created_on:
+      type: string
+      format: date-time
+      example:
+        '2020-12-07 09:48:01'
+    updated_on:
+      type: string
+      format: date-time
+      example:
+        '2021-01-01 15:30:00'
+    coll_id:
+      $ref: 'common.yaml#/ID'
+    collection_name:
+      type: string
+      example:
+        'collection de test'
+    witdh:
+      type: integer
+      example:
+        5616
+    height:
+      type: integer
+      example:
+        3744
+    size:
+      type: integer
+      example:
+        5618218
+    base_id:
+      $ref: 'common.yaml#/ID'
+    databox_id:
+      $ref: 'common.yaml#/ID'
+    databox_name:
+      type: string
+      example:
+        'db_databox1'
+    record_type:
+      type: string
+      enum: ['record','story']
+    title:
+      type: object
+      description: 'key->value list, where (key) is the lng, and (value) the title in this lng.'
+      additionalProperties: true
+      example:
+        fr: 'titre en Français'
+        en: 'title in english'
+        '': 'undefined-lng title ? To be fixed'
+    metadata_tags:
+      type: object
+      description: 'key->value list, where (key) is the name of the metadata, and (value) the value.'
+      additionalProperties: true
+      example:
+        Channels: 3
+        ColorDepth: 8
+        ColorSpace: 0
+        FileSize: 5618218
+        Height: 3744
+        MimeType: 'image/jpeg'
+        Width: 5616
+    caption:
+      type: object
+      description: >
+        'key->value list, where (key) is the field name, and (value) the value(s).'
+
+        'nb: mono-valued field value is a 1 element array.'
+      additionalProperties:
+        type: array
+        items:
+          type: string
+      example:
+        Artist: ['Bob']
+        Title: ['Cropped Hand Of Person Holding Computer Mouse']
+        Keywords: ['Hand', 'Mouse (computer)']
+    caption_all:
+      type: array
+      items:
+        type: string
+      description: >
+        'all fields values in a single array'
+      example: ['Bob','Cropped Hand Of Person Holding Computer Mouse','Hand','Mouse (computer)']
+    flags:
+      $ref: '#/Flags'
+    subdefs:
+      type: object
+      description: 'key->value list, where (key) is the name of the subdef, and (value) is the subdef object.'
+      additionalProperties:
+        type: object
+      example:
+        document:
+          type: object
+          properties:
+            width: 5616
+            height: 3744
+            size: 5618218
+            mime: 'image/jpeg'
+            permalink: 'http://localhost/permalink/v1/2/34/document/1134340545.jpg?token=xrdMnK6peB...'
+        thumbnail:
+          type: object
+          properties:
+            width: 1024
+            height: 683
+            size: 20011
+            mime: 'image/jpeg'
+            permalink: 'http://localhost/permalink/v1/2/34/preview/1134340545.jpg?token=E5aSbXQTmAz...'
+
+Flags:
+  type: object
+  description: 'key->value list, where (key) is the name of the flag (=status bit), and (value) is the boolean value.'
+  additionalProperties:
+    type: boolean
+  example:
+    public: true
+    color_checked: true
+    embargo: false
diff --git a/API_documentation/v3/parameters.yaml b/API_documentation/v3/parameters.yaml
new file mode 100644
index 0000000000..8a10243e10
--- /dev/null
+++ b/API_documentation/v3/parameters.yaml
@@ -0,0 +1,88 @@
+sbas_id:
+  name: sbas_id
+  in: path
+  description: ID of the databox
+  required: true
+  schema:
+    $ref: common.yaml#/ID
+
+base_id:
+  name: base_id
+  in: path
+  description: ID of the base
+  required: true
+  schema:
+    $ref: common.yaml#/ID
+
+record_id:
+  name: record_id
+  in: path
+  description: ID of the record
+  required: true
+  schema:
+    $ref: common.yaml#/ID
+
+query:
+  name: query
+  in: query
+  description: 'Fulltext query (<empty> = search all)'
+  required: false
+  schema:
+    type: string
+    example: 'dogs OR cats'
+    default: ''
+
+search_type:
+  name: search_type
+  in: query
+  required: false
+  schema:
+    type: integer
+    enum: [0,1]
+    default: 0
+  description: >
+    search for records or stories
+      * `0` - search for records
+      * `1` - search for stories
+
+page:
+  name: page
+  in: query
+  description: page number, from 1. Use along with "per_page"
+  required: false
+  schema:
+    type: integer
+    minimum: 1
+    default: 1
+
+per_page:
+  name: per_page
+  in: query
+  description: number of results per page. Use along with "page"
+  required: false
+  schema:
+    type: integer
+    minimum: 1
+    maximum: 100
+    default: 10
+
+offset:
+  name: offset
+  in: query
+  description: offset in records count, from 0. Use along with "limit"
+  required: false
+  schema:
+    type: integer
+    minimum: 0
+    # default: 0
+
+limit:
+  name: limit
+  in: query
+  description: number of results. Use along with "offset"
+  required: false
+  schema:
+    type: integer
+    minimum: 1
+    maximum: 100
+    # default:
diff --git a/API_documentation/v3/record.yaml b/API_documentation/v3/record.yaml
new file mode 100644
index 0000000000..c6adfe18a8
--- /dev/null
+++ b/API_documentation/v3/record.yaml
@@ -0,0 +1,119 @@
+  _Record_:
+    type: object
+    properties:
+      databox_id:
+        $ref: 'common.yaml#/ID'
+      record_id:
+        $ref: 'common.yaml#/ID'
+      title:
+        type: string
+      original_name:
+        type: string
+      updated_on:
+        type: string
+        format: date-time
+      created_on:
+        type: string
+        format: date-time
+      collection_id:
+        $ref: 'common.yaml#/ID'
+      base_id:
+        $ref: 'common.yaml#/ID'
+      thumbnail:
+        $ref: '#/Subdef'
+      uuid:
+        type: string
+
+  Record:
+    allOf:     # Combines the basic _Record_ and the records-only properties
+      - $ref: '#/_Record_'
+      - type: object
+        properties:
+          mime_type:
+            type: string
+          technical_informations:
+            type: array
+            items:
+              $ref: '#/TechnicalInformation'
+          sha256:
+            type: string
+          phrasea_type:
+            type: string
+            enum:
+              - image
+              - video
+
+  Story:
+    allOf:     # Combines the basic _Record_ and the stories-only properties
+      - $ref: '#/_Record_'
+      - type: object
+        properties:
+          children_offset:
+            type: integer
+            description: 'Children pagination offset ; Always 0'
+            example: 0
+          children_limit:
+            type: integer
+            description: 'Children pagination limit ; Equal to "story_children_limit" passed in request'
+            example: 10
+          children_count:
+            type: integer
+            description: 'Number of children in "children" array ; [0...limit]'
+            example: 5
+          children_total:
+            type: integer
+            description: 'Total number of __visibles for user__ children in this story'
+            example: 5
+          children:
+            type: array
+            items:
+              type: object
+              items:
+                $ref: '#/Record'
+
+  TechnicalInformation:
+    type: object
+    properties:
+      name:
+        type: string
+      value:
+        type: string
+
+  Subdef:
+    type: object
+    properties:
+      name:
+        type: string
+      permalink:
+        $ref: 'common.yaml#/PermalinkObject'
+      height:
+        type: integer
+      width:
+        type: integer
+      filesize:
+        type: integer
+      devices:
+        type: array
+        items:
+          type: string
+          enum:
+            - screen
+            - printer ?
+      player_type:
+        type: string
+        enum:
+          - IMAGE
+      mime_type:
+        type: string
+      substituted:
+        type: boolean
+      created_on:
+        type: string
+        format: date-time
+      updated_on:
+        type: string
+        format: date-time
+      url:
+        type: string
+      url_ttl:
+        type: integer
diff --git a/API_documentation/v3/responses.yaml b/API_documentation/v3/responses.yaml
index 1ac2155f3e..23fd724501 100644
--- a/API_documentation/v3/responses.yaml
+++ b/API_documentation/v3/responses.yaml
@@ -12,4 +12,4 @@ record_response:
         404:
             description: Record not found
 error_response:
-        description: Any (other) error
+        description: Any other error
diff --git a/API_documentation/v3/schemas.yaml b/API_documentation/v3/schemas.yaml
index 1c41793243..3a4cdb7f35 100644
--- a/API_documentation/v3/schemas.yaml
+++ b/API_documentation/v3/schemas.yaml
@@ -4,7 +4,7 @@ RecordPatch_metadata:
         field_name:
             type: string
         meta_struct_id:
-            $ref: '#/ID'
+            $ref: 'common.yaml#/ID'
         action:
             type: string
             enum:
@@ -64,46 +64,16 @@ ApiResponse_record:
         meta:
             $ref: '#/ApiResponse_meta'
         response:
-            $ref: '#/Record'
-
-# -------------------- searchraw ---------------
-ApiResponse_searchraw:
+            $ref: 'record.yaml#/Record'
+ApiResponse_story:
     type: object
     properties:
         meta:
             $ref: '#/ApiResponse_meta'
         response:
-            $ref: '#/ApiResponse_searchraw_response'
-ApiResponse_searchraw_response:
-    type: object
-    properties:
-        results:
-            type: array
-            items:
-                $ref: '#/ESRecord'
-        took:
-            type: integer
-            description: 'Search duration in msec'
-            example:
-                12
-#        offset:
-#            type: integer
-#            description: 'Pagination offset as passed (or computed from "page/per_page") in request'
-#        limit:
-#            type: integer
-#            description: 'Pagination limit as passed in request'
-        count:
-            type: integer
-            description: 'Number of results in this page [0...limit]'
-            example:
-                1
-        total:
-            type: integer
-            description: 'Total number of results'
-            example:
-                1
-        facets:
-            $ref: '#/FacetsArray'
+            $ref: 'record.yaml#/Story'
+
+# -------------------- searchraw ---------------
 
 # -------------------- search ---------------
 ApiResponse_search:
@@ -135,330 +105,15 @@ ApiResponse_search_response:
                 stories:
                     type: array
                     items:
-                        $ref: '#/Story'
+                        $ref: 'record.yaml#/Story'
                 records:
                     type: array
                     items:
-                        $ref: '#/Record'
+                        $ref: 'record.yaml#/Record'
         facets:
-            $ref: '#/FacetsArray'
+            $ref: 'common.yaml#/FacetsArray'
 
 
-ID:
-    type: integer
-
-Permalink:
-    type: object
-    properties:
-        created_on:
-            type: string
-            format: date-time
-        id:
-            $ref: '#/ID'
-        is_activated:
-            type: boolean
-        label:
-            type: string
-        updated_on:
-            type: string
-            format: date-time
-        page_url:
-            type: string
-        download_url:
-            type: string
-        url:
-            type: string
-
-Subdef:
-    type: object
-    properties:
-        name:
-            type: string
-        permalink:
-            $ref: '#/Permalink'
-        height:
-            type: integer
-        width:
-            type: integer
-        filesize:
-            type: integer
-        devices:
-            type: array
-            items:
-                type: string
-                enum:
-                    - screen
-                    - printer ?
-        player_type:
-            type: string
-            enum:
-                - IMAGE
-        mime_type:
-            type: string
-        substituted:
-            type: boolean
-        created_on:
-            type: string
-            format: date-time
-        updated_on:
-            type: string
-            format: date-time
-        url:
-            type: string
-        url_ttl:
-            type: integer
-
-TechnicalInformation:
-    type: object
-    properties:
-        name:
-            type: string
-        value:
-            type: string
-_Record_:
-    type: object
-    properties:
-        databox_id:
-            $ref: '#/ID'
-        record_id:
-            $ref: '#/ID'
-        title:
-            type: string
-        original_name:
-            type: string
-        updated_on:
-            type: string
-            format: date-time
-        created_on:
-            type: string
-            format: date-time
-        collection_id:
-            $ref: '#/ID'
-        base_id:
-            $ref: '#/ID'
-        thumbnail:
-            $ref: '#/Subdef'
-        uuid:
-            type: string
-
-ESRecord:
-    description: 'Raw response from es search on "record" index/mapping'
-    type: object
-    properties:
-        _index:
-            type: string
-            description: 'ES index'
-            example:
-                'phraseanet_dxmpcw3y8td68f+h_20201124161735.910647'
-        _type:
-            type: string
-            description: 'Data type'
-            example:
-                'record'
-        _id:
-            type: string
-            description: 'unique id of document (sbas_id + "_" + record_id)'
-            example:
-                '1_555'
-        _version:
-            type: integer
-            description: 'auto-increment at each indexation of the document'
-            example:
-                1
-        _score:
-            type: number
-            description: 'score of the document related to a whole resultset'
-            example:
-                1
-        _source:
-            $ref: '#/ESRecordSource'
-
-ESRecordSource:
-    type: object
-    properties:
-        record_id:
-            $ref: '#/ID'
-        collection_id:
-            $ref: '#/ID'
-        uuid:
-            type: string
-            example:
-                'dcee40ea-ee26-4d8b-b0c2-d61305b03bc0'
-        flags_bitfield:
-            type: integer
-        sha256:
-            type: string
-            example:
-                '7fad283de349b903c850548cda65cf2d86d24c4e3856cdc2b97e47430494b8c8'
-        original_name:
-            type: string
-            example:
-                '1134340545.jpg'
-        mime:
-            type: string
-            example:
-                'image/jpeg'
-        type:
-            type: string
-            example:
-                'image'
-        created_on:
-            type: string
-            format: date-time
-            example:
-                '2020-12-07 09:48:01'
-        updated_on:
-            type: string
-            format: date-time
-            example:
-                '2021-01-01 15:30:00'
-        coll_id:
-            $ref: '#/ID'
-        collection_name:
-            type: string
-            example:
-                'collection de test'
-        witdh:
-            type: integer
-            example:
-                5616
-        height:
-            type: integer
-            example:
-                3744
-        size:
-            type: integer
-            example:
-                5618218
-        base_id:
-            $ref: '#/ID'
-        databox_id:
-            $ref: '#/ID'
-        databox_name:
-            type: string
-            example:
-                'db_databox1'
-        record_type:
-            type: string
-            enum: ['record','story']
-        title:
-            type: object
-            description: 'key->value list, where (key) is the lng, and (value) the title in this lng.'
-            additionalProperties: true
-            example:
-                fr: 'titre en Français'
-                en: 'title in english'
-                '': 'undefined-lng title ? To be fixed'
-        metadata_tags:
-            type: object
-            description: 'key->value list, where (key) is the name of the metadata, and (value) the value.'
-            additionalProperties: true
-            example:
-                Channels: 3
-                ColorDepth: 8
-                ColorSpace: 0
-                FileSize: 5618218
-                Height: 3744
-                MimeType: 'image/jpeg'
-                Width: 5616
-        caption:
-            type: object
-            description: >
-                'key->value list, where (key) is the field name, and (value) the value(s).'
-
-                'nb: mono-valued field value is a 1 element array.'
-            additionalProperties:
-                type: array
-                items:
-                    type: string
-            example:
-                Artist: ['Bob']
-                Title: ['Cropped Hand Of Person Holding Computer Mouse']
-                Keywords: ['Hand', 'Mouse (computer)']
-        caption_all:
-            type: array
-            items:
-                type: string
-            description: >
-                'all fields values in a single array'
-            example: ['Bob','Cropped Hand Of Person Holding Computer Mouse','Hand','Mouse (computer)']
-        flags:
-            $ref: '#/Flags'
-        subdefs:
-            type: object
-            description: 'key->value list, where (key) is the name of the subdef, and (value) is the subdef object.'
-            additionalProperties:
-                type: object
-            example:
-                document:
-                    type: object
-                    properties:
-                        width: 5616
-                        height: 3744
-                        size: 5618218
-                        mime: 'image/jpeg'
-                        permalink: 'http://localhost/permalink/v1/2/34/document/1134340545.jpg?token=xrdMnK6peB...'
-                thumbnail:
-                    type: object
-                    properties:
-                        width: 1024
-                        height: 683
-                        size: 20011
-                        mime: 'image/jpeg'
-                        permalink: 'http://localhost/permalink/v1/2/34/preview/1134340545.jpg?token=E5aSbXQTmAz...'
-
-Flags:
-    type: object
-    description: 'key->value list, where (key) is the name of the flag (=status bit), and (value) is the boolean value.'
-    additionalProperties:
-        type: boolean
-    example:
-        public: true
-        color_checked: true
-        embargo: false
-
-Record:
-    allOf:     # Combines the basic _Record_ and the records-only properties
-        - $ref: '#/_Record_'
-        - type: object
-          properties:
-            mime_type:
-                type: string
-            technical_informations:
-                type: array
-                items:
-                    $ref: '#/TechnicalInformation'
-            sha256:
-                type: string
-            phrasea_type:
-                type: string
-                enum:
-                    - image
-                    - video
-
-Story:
-    allOf:     # Combines the basic _Record_ and the stories-only properties
-        - $ref: '#/_Record_'
-        - type: object
-          properties:
-            children_offset:
-                type: integer
-                description: 'Children pagination offset ; Always 0'
-            children_limit:
-                type: integer
-                description: 'Children pagination limit ; Equal to "story_children_limit" passed in request'
-            children_count:
-                type: integer
-                description: 'Number of children in "children" array ; [0...limit]'
-            children_total:
-                type: integer
-                description: 'Total number of -visibles for user- children in this story'
-            children:
-                type: array
-                items:
-                    type: object
-                    items:
-                        $ref: '#/Record'
 
 RecordUri:
     type: string
@@ -477,38 +132,3 @@ ApiResponse_RecordsUriArray:
         response:
             $ref: '#/RecordsUriArray'
 
-Facet:
-    type: object
-    properties:
-        name:
-            type: string
-            description: 'Unique internal name (=key) for the facet'
-            example: '_base'
-        field:
-            type: string
-            description: 'Source field (from db structure). Can be also virtual field like "database" '
-            example: 'database'
-        values:
-            type: array
-            items:
-                type: object
-                properties:
-                    value:
-                        type: string
-                        description: 'Human readable value for the value'
-                        example: 'Demo'
-                    raw_value:
-                        type: string
-                        description: 'Real value, to be used to query'
-                        example: 'db_demo'
-                    count:
-                        type: integer
-                        description: 'Number of items matching this value'
-                    query:
-                        type: string
-                        description: 'Formulated query to search items matching this facet'
-                        example: 'database:db_demo'
-FacetsArray:
-    type: array
-    items:
-        $ref: '#/Facet'
\ No newline at end of file
diff --git a/API_documentation/v3/search.yaml b/API_documentation/v3/search.yaml
new file mode 100644
index 0000000000..d33ba55ae4
--- /dev/null
+++ b/API_documentation/v3/search.yaml
@@ -0,0 +1,39 @@
+
+  ApiResponse_search:
+    type: object
+    properties:
+      meta:
+        $ref: 'common.yaml#/ApiResponse_meta'
+      response:
+        $ref: '#/ApiResponse_search_response'
+
+  ApiResponse_search_response:
+    type: object
+    properties:
+      offset:
+        type: integer
+        description: 'Pagination offset as passed (or computed from "page/per_page") in request'
+      limit:
+        type: integer
+        description: 'Pagination limit as passed in request'
+      count:
+        type: integer
+        description: 'Number of results in this page [0...limit]'
+      total:
+        type: integer
+        description: 'Total number of results'
+        minimum: 1
+      results:
+        type: object
+        properties:
+          stories:
+            type: array
+            items:
+              $ref: 'record.yaml#/Story'
+          records:
+            type: array
+            items:
+              $ref: 'record.yaml#/Record'
+      facets:
+        $ref: 'common.yaml#/FacetsArray'
+
diff --git a/API_documentation/v3/searchraw.yaml b/API_documentation/v3/searchraw.yaml
new file mode 100644
index 0000000000..bf758bbcf9
--- /dev/null
+++ b/API_documentation/v3/searchraw.yaml
@@ -0,0 +1,38 @@
+ApiResponse_searchraw:
+  type: object
+  properties:
+    meta:
+      $ref: 'common.yaml#/ApiResponse_meta'
+    response:
+      $ref: '#/ApiResponse_searchraw_response'
+
+ApiResponse_searchraw_response:
+  type: object
+  properties:
+    results:
+      type: array
+      items:
+        $ref: 'es.yaml#/ESRecord'
+    took:
+      type: integer
+      description: 'Search duration in msec'
+      example:
+        12
+    #        offset:
+    #            type: integer
+    #            description: 'Pagination offset as passed (or computed from "page/per_page") in request'
+    #        limit:
+    #            type: integer
+    #            description: 'Pagination limit as passed in request'
+    count:
+      type: integer
+      description: 'Number of results in this page [0...limit]'
+      example:
+        1
+    total:
+      type: integer
+      description: 'Total number of results'
+      example:
+        1
+    facets:
+      $ref: 'common.yaml#/FacetsArray'