diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c2df59
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+distromatic project for the *openmamba Linux* distribution
+==================================================
+This project provides tools that have been developed by the maintainers of the *openmamba Linux* distribution in order to maintain, monitor and provide user interfaces for RPM based package repositories.
+
+## `distromatic` tool
+`distromatic` is a command line tool which scans repositories with `rpm` and `srpm` packages or `repodata` folders containing metadata files and provides output files as *sqlite* databases, plaintext and html with detailed information on repositories and packages.
+
+The created files are used for distribution maintainance purposes and to provide informative interfaces to end users.
+
+## `distroquery` tool
+`distroquery` is a command line tool intended to be used as a `CGI` backend for the web. It provides **API** interfaces intended to be used by *web frontends* and *development instruments* in order to provide dynamic information on distribution repositories and packages.
+
+### `distroquery` API services
+The newest distroquery API interface is currently available from this prefix: [https://push.openmamba.org/openmamba/distroquery/api/v1](https://push.openmamba.org/openmamba/distroquery/api/v1).
+
+#### Sample endpoints
+
+* Repositories list: [https://push.openmamba.org/openmamba/distroquery/api/v1/repositories](https://push.openmamba.org/openmamba/distroquery/api/v1/repositories)
+* Repository packages: [https://push.openmamba.org/openmamba/distroquery/api/v1/repository/base?page=1&per_page=10](https://push.openmamba.org/openmamba/distroquery/api/v1/repository/base?page=1&per_page=10)
+* Source package details: [https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash](https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash)
+* Binary package details: [https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash/x86_64](https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash/x86_64)
+* Binary package files list: [https://push.openmamba.org/openmamba/distroquery/api/v1/package_files/base/bash/x86_64](https://push.openmamba.org/openmamba/distroquery/api/v1/package_files/base/bash/x86_64)
+* Providers for file: [https://push.openmamba.org/openmamba/distroquery/api/v1/file_providers/base/%2Fbin%2Fbash/x86_64](https://push.openmamba.org/openmamba/distroquery/api/v1/file_providers/base/%2Fbin%2Fbash/x86_64)
+* Providers for requirement: [https://push.openmamba.org/openmamba/distroquery/api/v1/providers/base/glibc/>=/2.40](https://push.openmamba.org/openmamba/distroquery/api/v1/providers/base/glibc/>=/2.40)
+* Repository problems: [https://push.openmamba.org/openmamba/distroquery/api/v1/problems/base](https://push.openmamba.org/openmamba/distroquery/api/v1/problems/base)