diff --git a/doc/api/api.md b/doc/api/api.md
index c627b2b3b..8d82ebb75 100644
--- a/doc/api/api.md
+++ b/doc/api/api.md
@@ -1,13 +1,20 @@
 # Grin API Documentation
 
-This document contains the documentation for the Node Grin REST API.
+Used to query a node about various information on the blockchain, networks and peers. By default, the API will listen on `localhost:3413`. The API is started as the same time as the Grin node.
+This endpoint requires, by default, [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). The username is `grin`.
 
-## Node API
+## Node API v2
 
-This endpoint is used to query a node about various information on the blockchain, networks and peers. By default, this REST API will listen on `localhost:3413`. This API is started as the same time as the Grin node.
-This endpoint requires, by default, [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). The username is `grin` and the password can be found in the `.api_secret` file.
-To learn about what specific calls can be made read the [node API doc](node_api.md).
+This API version uses jsonrpc for its requests. It is split up in a foreign API and an owner API. The documentation for these endpoints is automatically generated:
+- [Owner API](https://docs.rs/grin_api/latest/grin_api/trait.OwnerRpc.html)
+- [Foreign API](https://docs.rs/grin_api/latest/grin_api/trait.ForeignRpc.html)
 
-## Ports above 10000?
+Basic auth passwords can be found in `.api_secret`/`.foreign_api_secret` files respectively.
 
-All ports should be below 10000 when running with default settings on mainnet. If your grin owner_api is using the 13420 port but is on mainnet, then you're using an outdated version of grin.
+## Node API v1
+
+**Note:** version 1 of the API will be deprecated in v4.0.0 and subsequently removed in v5.0.0. Users of this API are encouraged to upgrade to API v2.
+
+This API uses REST for its requests. To learn about what specific calls can be made read the [node API v1 doc](node_api_v1.md).
+
+Basic auth password can be found in `.api_secret`
diff --git a/doc/api/node_api.md b/doc/api/node_api_v1.md
similarity index 99%
rename from doc/api/node_api.md
rename to doc/api/node_api_v1.md
index 63f995883..722277eb7 100644
--- a/doc/api/node_api.md
+++ b/doc/api/node_api_v1.md
@@ -1,4 +1,4 @@
-# Node API Documentation
+# Node API v1 Documentation
 
 ## Table of Contents