diff --git a/README.md b/README.md
index a2a53a2..602f567 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,6 @@ transfer to Docker Hub.
 
 ## open TODOs
 there are still some open TODOs
-* explain Pipeline, VERSION, open-api-3.yaml
 * system view as image?  
 * structure oriented on https://github.com/golang-standards/project-layout  
 * how to fork (github credentials, ...)  
@@ -72,6 +71,8 @@ contribute to making containerization as efficient as possible.
    is responsible for building the [Docker](https://www.docker.com/) image and pushing it to [Docker Hub](https://hub.docker.com/).
    Repository secrets _DOCKER_USERNAME_ and _DOCKER_PASSWORD_ are required as documented in Part [How to use this example](#how-to-use-this-example).
 
+TODO version replacement
+
 ### Where are the unit tests?
 
 This is a simple illustration that shows the interaction between [Go](https://go.dev/), [Docker](https://www.docker.com/), [Docker Hub](https://hub.docker.com/) and 
diff --git a/api/open-api-3.yaml b/api/open-api-3.yaml
index 803cd13..1d9b2aa 100644
--- a/api/open-api-3.yaml
+++ b/api/open-api-3.yaml
@@ -12,5 +12,27 @@ info:
     url: https://www.apache.org/licenses/LICENSE-2.0
 
 paths:
-
-#TODO
\ No newline at end of file
+  /api:
+    get:
+      summary: Retrieves the OpenAPI description as yaml
+      responses:
+        200:
+          description: Successful operation
+          content:
+            text/yaml:
+              schema:
+                type: string
+  /api/external:
+    get:
+      summary: Calls a configured external URL (in this example https://catfact.ninja/fact) and returns the response (a fact about cats) as JSON
+      responses:
+        200:
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  fact: "A cat sees about 6 times better than a human at night, and needs 1/6 the amount of of light that a human does - it has a layer of extra reflecting cells which absorb light.",
+                  length: 172
+                }
\ No newline at end of file