docs(api): update api doc explanation

docs/api.md

@@ -8,7 +8,7 @@ By default, no tokens are exposed in an output file unless specifically designat
 |---|---|---|
 | attributes {category/type/option} | string | Follow the pattern of the [CTI Structure](https://amzn.github.io/style-dictionary/#/properties?id=category-type-item) to determine the value of a category, type or option in the JSON |
 | classic | boolean | Token filter for `classic` theme values |
-| deprecated | boolean | Tokens marked as `deprecated:false` will be included into the AllTokens data file. Ones marked `deprecated:true` will only appear in the deprecated data. |
+| deprecated | boolean | Tokens marked as `deprecated:false` will be included into the AllTokens data file. Ones marked `deprecated:true` will only appear in the deprecated data. This should be used in conjunction with the redirect and reference JSON options in order to properly deprecate the token and reference it's replacement (or n/a). |
 | legacy | boolean | Token filter for legacy values |
 | opacity | boolean | Token filter for base colors with an alpha transparency |
 | public | boolean | Token filter for publicly exposed Design System tokens per the most recent spec |