diff --git a/API_documentation/v3/api.yaml b/API_documentation/v3/api.yaml
new file mode 100644
index 0000000000..2b60ff2b4f
--- /dev/null
+++ b/API_documentation/v3/api.yaml
@@ -0,0 +1,108 @@
+openapi: 3.0.0
+info:
+    description: >
+        This is a demonstration 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)
+    - url: https://beta.preprod.alchemyasp.com/api/v3
+      description: Phraseanet beta
+security:
+    - api_key: []
+    - oAuth2Password: []
+components:
+    securitySchemes:
+        api_key:
+            type: apiKey
+            name: oauth_token
+            in: query
+        oAuth2Password:
+            type: oauth2
+            description: This API uses OAuth 2 with the password grant flow. [More info](https://api.example.com/docs/auth)
+            flows:
+                password:   # <-- OAuth flow(authorizationCode, implicit, password or clientCredentials)
+                    tokenUrl: azea
+paths:
+    '/me':
+        get:
+            description: 'blabla'
+            servers:
+                - url: 'https://alpha.preprod.alchemyasp.com/api/v1'
+            responses:
+                '200':
+                    description: successful operation
+                '400':
+                    description: Any other error
+                '404':
+                    description: Record not found
+
+    '/records/{base_id}':
+        post:
+            tags:
+                - record
+            summary: Creates a record
+            description: 'Creates a single record, including document and/or data.'
+            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 (document)'
+                            allOf:
+                                - $ref: schemas.yaml#/RecordPatch
+            responses:
+                default:
+                    $ref: responses.yaml#/record_response
+            security:
+                - api_key: []
+    '/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:
+                - name: sbas_id
+                  in: path
+                  description: ID of the databox
+                  required: true
+                  schema:
+                      $ref: schemas.yaml#/ID
+                - name: record_id
+                  in: path
+                  description: ID of the record
+                  required: true
+                  schema:
+                      $ref: schemas.yaml#/ID
+            responses:
+                default:
+                    $ref: responses.yaml#/record_response
diff --git a/API_documentation/v3/responses.yaml b/API_documentation/v3/responses.yaml
new file mode 100644
index 0000000000..9e4e4972c7
--- /dev/null
+++ b/API_documentation/v3/responses.yaml
@@ -0,0 +1,11 @@
+record_response:
+    '200':
+        description: successful operation
+        content:
+            application/json:
+                schema:
+                    $ref: schemas.yaml#/ApiResponse_record
+    '400':
+        description: Any other error
+    '404':
+        description: Record not found
\ No newline at end of file
diff --git a/API_documentation/v3/schemas.yaml b/API_documentation/v3/schemas.yaml
new file mode 100644
index 0000000000..77c30061e1
--- /dev/null
+++ b/API_documentation/v3/schemas.yaml
@@ -0,0 +1,172 @@
+RecordPatch_metadata:
+    type: object
+    properties:
+        field_name:
+            type: string
+        meta_struct_id:
+            $ref: '#/ID'
+        action:
+            type: string
+            enum:
+                - set
+                - add
+                - delete
+                - replace
+        value:
+            # todo : change to string, int, number, array
+            type: string
+RecordPatch_status:
+    type: object
+    required:
+        - bit
+        - state
+    properties:
+        bit:
+            type: integer
+            minimum: 4
+            maximum: 31
+        state:
+            type: boolean
+RecordPatch:
+    description: 'Metadata, status, collection, etc to be set for a record'
+    type: object
+    properties:
+        metadatas:
+            type: array
+            items:
+                $ref: '#/RecordPatch_metadata'
+        status:
+            type: array
+            items:
+                $ref: '#/RecordPatch_status'
+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
+ApiResponse_record:
+    type: object
+    properties:
+        meta:
+            $ref: '#/ApiResponse_meta'
+        response:
+            $ref: '#/Record'
+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'
+        mime_type:
+            type: string
+        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'
+        sha256:
+            type: string
+        thumbnail:
+            $ref: '#/Subdef'
+        technical_informations:
+            type: array
+            items:
+                $ref: '#/TechnicalInformation'
+        phrasea_type:
+            type: string
+            enum:
+                - image
+                - video
+        uuid:
+            type: string
+