diff --git a/docs/api/changes.md b/docs/api/changes.md
index 4b1564877bbf17af11bf1d82ba00a94da1345c68..35de0f7a2e60e6a4abcf2669e30f9161031b2981 100644
--- a/docs/api/changes.md
+++ b/docs/api/changes.md
@@ -4,6 +4,10 @@ This page lists changes to CiviCRM core which affect the ways in which developer
 
 ## APIv3: Framework
 
+### 5.8 Support for Extension Examples in the API Explorer.
+
+From 5.8 it is now possible for Extension authors to store examples for their API entities in a folder `<extensiondir>/api/v3/examples/<entity>/<file>` in the same structure as is in core. They will now be displayed in the API Explorer just like the core examples.
+
 ### 5.0 Support for custom data on any entity via the api
 It is now possible to add any (almost) entity to the cg_group_extends option group and create / retrieve custom data for that field via the api (also custom entities). Ones that do not work as of 5.0 release are       
       'CaseContact',
diff --git a/docs/api/index.md b/docs/api/index.md
index a80097d2bb4b05f0a4beab375330a409fd148f84..f2e13f1436503a3dc0cef4d428569a5104392623 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -47,6 +47,10 @@ action or complete your create or update action.
 
 From the API explorer, you can click on the **Examples** tab to find examples of API calls which are based on automated tests within the source code. You can also [explore these examples on GitHub](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples).
 
+### API Examples in your extensions
+
+From CiviCRM v5.8 the APIv3 explorer will now be able to show examples that are stored in your extension. The only requirement is that they are found in the same sort of directory structure as core e.g. in `<yourextension>/api/v3/examples/<entity>/<file>`
+
 ## Changelog
 
 All important changes made to the API are recorded in [API changes](/api/changes.md).