diff --git a/docs/source/development/api.rst b/docs/source/development/api.rst
index 86eb6ff65..d6f63eea3 100644
--- a/docs/source/development/api.rst
+++ b/docs/source/development/api.rst
@@ -450,4 +450,39 @@ Full configuration example
                        single-collection: single
                base_role: null
 
+Maintaining an OpenApi
+======================
+
+.. note::
+
+   This is experimental and may change. Keep reading this part.
+
+Accessing swagger
+-----------------
+
+The swagger UI is accessible through `<http://localhost:8001/_dev/swagger>`_
+
+This is possible only in development mode.
+
+You must be authenticated with a valid user to access it.
+
+Maintaining specs
+-----------------
+
+Each bundle should have an `open api 3.0 spec file <https://swagger.io/docs/specification/about/>`_ at the bundle's root, and name :code:`chill.api.specs.yaml`.
+
+.. warning::
+
+   Update the command :code:`specs-build` into `package.json` when adding a new api file.
+
+The specs may be compiled from the different bundles filed, and validated using docker node:
+
+.. code-block:: bash
+
+   ./docker-node.sh
+   # build the openapi
+   yarn specs-build
+   # validate
+   yarn specs-validate
+
 
diff --git a/src/Bundle/ChillMainBundle/chill.api.specs.yaml b/src/Bundle/ChillMainBundle/chill.api.specs.yaml
new file mode 100644
index 000000000..ada65b08a
--- /dev/null
+++ b/src/Bundle/ChillMainBundle/chill.api.specs.yaml
@@ -0,0 +1,59 @@
+---
+openapi: "3.0.0"
+info:
+  version: "1.0.0"
+  title: "Chill api"
+  description: "Api documentation for chill. Currently, work in progress"
+servers:
+  - url: "/api"
+    description: "Your current dev server"
+
+components:
+  parameters:
+    _format:
+      name: _format
+      in: path
+      required: true
+      schema:
+        type: string
+        enum:
+          - json
+
+paths:
+  /1.0/search.json:
+    get:
+      summary: perform a search across multiple entities
+      tags:
+        - search
+        - person
+        - thirdparty
+      description: >
+        **Warning**: This is currently a stub (not really implemented
+
+        The search is performed across multiple entities. The entities must be listed into 
+        `type` parameters.
+
+        The results are ordered by relevance, from the most to the lowest relevant.
+
+      parameters:
+        - name: q
+          in: query
+          required: true
+          description: the pattern to search
+          schema:
+            type: string
+        - name: type[]
+          in: query
+          required: true
+          description: the type entities amongst the search is performed
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - person
+                - thirdparty
+      responses:
+        200:
+          description: "OK"
+
diff --git a/src/Bundle/ChillPersonBundle/chill.api.specs.yaml b/src/Bundle/ChillPersonBundle/chill.api.specs.yaml
new file mode 100644
index 000000000..0713afd8d
--- /dev/null
+++ b/src/Bundle/ChillPersonBundle/chill.api.specs.yaml
@@ -0,0 +1,91 @@
+components:
+  schemas:
+    PersonById:
+      type: object
+      properties:
+        person_id:
+          type: integer
+      required:
+        - person_id
+    ThirdPartyById:
+      type: object
+      properties:
+        thirdparty_id:
+          type: integer
+      required:
+        - thirdparty_id
+
+
+paths:
+  /1.0/person/accompanying-course/{id}.json:
+    get:
+      tags:
+        - person
+      summary: "Return the description for an accompanying course (accompanying period)"
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The accompanying period's id
+          schema:
+            type: integer
+            format: integer
+            minimum: 1
+      responses:
+        401:
+          description: "Unauthorized"
+        404:
+          description: "Not found"
+        200:
+          description: "OK"
+  /1.0/person/accompanying-course/{id}/requestor.json:
+    post:
+      tags:
+        - person
+      summary: "Add a requestor to the accompanying course"
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The accompanying period's id
+          schema:
+            type: integer
+            format: integer
+            minimum: 1
+      requestBody:
+        description: "A person or thirdparty"
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - $ref: '#/components/schemas/PersonById'
+                - $ref: '#/components/schemas/ThirdPartyById'
+      responses:
+        401:
+          description: "Unauthorized"
+        404:
+          description: "Not found"
+        200:
+          description: "OK"
+    delete:
+      tags:
+        - person
+      summary: "Remove the requestor for the accompanying course"
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The accompanying period's id
+          schema:
+            type: integer
+            format: integer
+            minimum: 1
+      responses:
+        401:
+          description: "Unauthorized"
+        404:
+          description: "Not found"
+        200:
+          description: "OK"
+