diff --git a/docs/REGISTRY-API.md b/docs/REGISTRY-API.md
index e0fb487..5ddf0ed 100644
--- a/docs/REGISTRY-API.md
+++ b/docs/REGISTRY-API.md
@@ -108,11 +108,20 @@
 
 This endpoint responds with the package metadata document, sometimes informally called a "packument" or "doc.json". The format of the response is described in detail in the [package metadata documentation](responses/package-metadata.md).
 
+**Scoped packages:** The `{package}` path segment must be percent-encoded. The `/` separator between scope and name must be encoded as `%2f` (or `%2F`):
+
+```
+GET /@babel%2fcore
+GET /@types%2fnode
+```
+
+A literal `/` in the path (e.g. `/@babel/core`) is treated as two separate path segments and will not resolve correctly. Registry implementations must not decode `%2f` to `/` before routing the request.
+
 #### `GET·/{package}/{version}`
 
 | Name     | Value     | Kind     | Required?     | Notes     |
 |------    |-------    |------    |-----------    |-------    |
-| package | String | **Path** | ✅         | the name of the package |
+| package | String | **Path** | ✅         | the name of the package; scoped packages must use `%2f` for the `/` separator (e.g. `@babel%2fcore`) |
 | version | String | **Path** | ✅         | a version number or `latest`        |
 
 #### `GET·/-/v1/search`