diff --git a/docs/stubs_to_sources.py b/docs/stubs_to_sources.py
index 4c3595f..7ea6bda 100644
--- a/docs/stubs_to_sources.py
+++ b/docs/stubs_to_sources.py
@@ -22,6 +22,7 @@
 referencing a type not declared yet (i.e. forward reference)."""
 
 import ast
+import inspect
 from collections import defaultdict
 from pathlib import Path
 
@@ -29,6 +30,15 @@
 __INIT__ = PACKAGE / "__init__.py"
 
 
+def _unstable(item):
+    warning = "Warning: This API has been marked as unstable: it works as advertised, but it may be changed in a future release."
+    if item.__doc__:
+        item.__doc__ += "\n" + warning
+    else:
+        item.__doc__ = warning
+    return item
+
+
 class RemoveOverload(ast.NodeTransformer):
     def __init__(self):
         self.current_cls = None
@@ -95,10 +105,16 @@ def main():
         entry.rename(PACKAGE / f"{entry.stem}.py")
     # read stub code
     with open(__INIT__) as f:
-        stub = ast.parse(f.read())
+        stub: ast.Module = ast.parse(f.read())
+    # replace _unstable
+    for i, stmt in enumerate(stub.body):
+        if isinstance(stmt, ast.FunctionDef) and stmt.name == "_unstable":
+            stub.body[i] = ast.parse(inspect.getsource(_unstable))
+    # remove overload
+    stub = RemoveOverload().visit(stub)
     # write modified code
     with open(__INIT__, "w") as f:
-        f.write(ast.unparse(RemoveOverload().visit(stub)))
+        f.write(ast.unparse(stub))
 
 
 if __name__ == "__main__":
diff --git a/zenoh/__init__.pyi b/zenoh/__init__.pyi
index 007fa6d..d736055 100644
--- a/zenoh/__init__.pyi
+++ b/zenoh/__init__.pyi
@@ -32,6 +32,9 @@ _RustHandler = (
 _PythonCallback = Callable[[_T], Any]
 _PythonHandler = tuple[_PythonCallback[_T], _H]
 
+def _unstable(item: _T) -> _T:
+    """marker for unstable items"""
+
 @final
 class ZError(Exception): ...