Merge branch 'main' into DDOC-1226-publishing

Author: superojla

content/guides/api-calls/api-versioning-strategy.md

@@ -13,35 +13,58 @@ API versioning empowers Box to continually enhance its platform, while also offe
 
 <Message type='tip'>
 
-To stay informed about the forthcoming API modifications, monitor the [Changelog](https://developer.box.com/changelog/) and maintain a current email address in the Developer Console's App Info section.
+To stay informed about the forthcoming API modifications, monitor the [Changelog](page://changelog) and maintain a current email address in the Developer Console's App Info section.
 
 </Message>
 
-## How Box API versioning works
-
+<!-- Commenting this until we enable base version support in Public API Service
 <Message type='notice'>
 
-Box API supports versioning in URL `path` and `header`. To determine which version to use, look at the API reference and included sample requests.
+In 2024, Box introduced year-based API versioning.
+
+All endpoints available at the end of 2024 were assigned the version `2024.0`.
+
+**No action is required for API users to continue using Box APIs.**
+
+To make version-aware API calls, include the `box-version` header with the value `2024.0` in your requests.
 
 </Message>
+-->
+
+## How Box API versioning works
 
-### Versioning in `path`
+<Message type='notice'>
 
-The default version of the API used in any requests is specified in the URL of the endpoint you call.
-For example, when calling the `https://upload.box.com/api/2.0/files/content` endpoint without any version header specified, you reach the `2.0` version defined in the URL.
+Box API supports versioning in `header`. To determine which version to use, look at the API reference and included sample requests.
 
-If there is a significant change to API behavior, the new endpoint will be exposed under the new URL.
-For example, `https://upload.box.com/api/2.0/files/content` supports a multipart content type when uploading files to Box. If the new version of this API stops supporting this content type, it will be released under a new URL `https://upload.box.com/api/3.0/files/content`.
+</Message>
 
 ### Versioning in `header`
 
-Box API processes the `box-version` header which should contain a valid version name, that is `box-version: 2025.0` and be directed at `https://api.box.com/2.0/files/:file_id/metadata`.
+Box API processes the `box-version` header which should contain a valid version name. For example, when a client wants
+to get a list of all sign requests using version `2025.0`, the request should look like this:
+
+```curl
+curl --location 'https://api.box.com/2.0/sign_requests' \
+     --header 'box-version: 2025.0' \
+     --header 'Authorization: Bearer …
+```
+
+If the provided version is correct and supported by the endpoint, a response is sent to the client.
+If the endpoint is available in multiple versions, the response will include the `box-version` header,
+which indicates the version used to handle the request.
+Endpoints introduced after 2024 may return a `400` error code if the version is incorrect.
+More information about versioning errors can be found [here](g://api-calls/permissions-and-errors/versioning-errors).
 
-If the provided version is correct, a response is sent back to the client. The response also contains the `box-version` header if it was provided in the request. By default, this header is not present in the response. If the version is wrong, an error with the HTTP code `400` is returned to the client.
+If your request doesn't include a version, the API defaults to the initial Box API version - `2024.0` - the version of endpoints available before
+year-based versioning was introduced. However, relying on this behavior is not recommended when adopting deprecated
+changes. To ensure consistency, always specify the API version, with each request. By making your application
+version-aware, you anchor it to a specific set of features, ensuring consistent behavior throughout the supported
+timeframe.
 
 ## Release schedule and naming convention
 
-Box can introduce a new breaking change to certain endpoints **once per year**. 
+Box can introduce a new breaking change to certain endpoints **once per year**, which results in a new API version.
 Introducing a new version of the Sign Request endpoint means that **all paths and HTTP methods** of an endpoint will support it.
 
 For example, if Sign Request endpoints receive a new version it will apply to all endpoints listed in the table:
@@ -69,12 +92,6 @@ It also means, that a new version cannot be released sooner than every 12 months
 
 We strongly recommend updating your apps to make requests to the latest stable API version. However, if your app uses a stable version that is no longer supported, then you will get a response with an HTTP error code `400 - Bad Request`. For details, see [Versioning Errors](g://api-calls/permissions-and-errors/versioning-errors).
 
-If your request doesn't include a version, the API defaults to the initial Box API version—the version available before 
-year-based versioning was introduced. However, relying on this behavior is not recommended when adopting deprecated 
-changes. To ensure consistency, always specify the API version, with each request. By making your application 
-version-aware, you anchor it to a specific set of features, ensuring consistent behavior throughout the supported 
-timeframe.
-
 ### Endpoint versioning indication
 
 To keep you informed about the current API state, and improve the readability of the versioned API reference, the affected endpoints are marked with a pill based on the `x-stability-level` tag or `deprecated` attribute.
@@ -83,22 +100,10 @@ To keep you informed about the current API state, and improve the readability of
 
 |    Schema element   | Pill name | Description|
 |---------------------|-----------|------------|
-| `x-stability-level: beta` | Beta | Endpoints marked with **beta**, are offered subject to Box’s Main Beta Agreement, meaning the available capabilities may change at any time. Although beta endpoints not the same as versioned endpoints, they are a part of API lifecycle. |
-|`x-stability-level: stable` or no `x-stability-level` tag  | Latest version | The latest version applies to APIs that are already versioned. **Latest version** marks the most recent stable API version of an endpoint.| 
+| `x-stability-level: beta` | Beta | Endpoints marked with **beta**, are offered subject to Box’s Main Beta Agreement, meaning the available capabilities may change at any time. When the beta endpoint becomes stable, the **beta** indication is removed. |
+|`x-stability-level: stable` or no `x-stability-level` tag  | Latest version | **Latest version** marks the most recent stable API version of an endpoint.|
 | `deprecated: true` | Deprecated |  An endpoint is deprecated, which means it is still available for use, but no new features are added. Such an endpoint is annotated with the `deprecated` attribute set to `true`.|
 
-## Calling an API version
-
-Box API versions are explicitly declared in the `box-version` header that your app makes requests to. For example:
-
-```curl
-curl --location 'https://api.box.com/2.0/sign_requests' \
-    --header 'box-version: 2025.0' \
-    --header 'Authorization: Bearer …
-```
-
-The client gets a list of all created sign requests and asks for version `2025.0`. There are several supported versions of the APIs available, and you specify the version that you want to use with the `box-version` header. There are three types of API versions: **stable**, **deprecated**, and **unstable**.
-
 ## Versioning errors
 
 When using versioned API actions such as calling an incorrect API version in header or a deprecated version can lead to errors.
@@ -107,7 +112,7 @@ For details on possible errors, see [versioning errors](g://api-calls/permission
 
 ## How Box SDK versioning works
 
-The versioning strategy applies only to [next generation generated SDKs](https://developer.box.com/sdks-and-tools/#next-generation-sdks).
+The versioning strategy applies only to [next generation generated SDKs](page://sdks-and-tools/#next-generation-sdks).
 
 Box SDKs support the **All Versions In** SDK approach.
 This means that every release of SDK provides access to all endpoints in any version which is currently live. All generated SDKs use manager's approach - they group all endpoints with the same domain in one manager.
@@ -208,14 +213,14 @@ When new versions of the Box APIs and Box SDKs are released, earlier versions wi
 sooner than after 24 months.
 Similarly, for individual APIs that are generally available (GA), Box declares an API as `deprecated` at least 24 months in advance of removing it from the GA version.
 
-When we increment the major version of the API (for example, from `2024.0` to `2025.0`), we're announcing that the current version (in this example, `2024.0`) is immediately deprecated and we'll no longer support it 24 months after the announcement. We might make exceptions to this policy for service security or health reliability issues.
+When we increment the major version of the API (for example, from `2025.0` to `2026.0`), we're announcing that the current version (in this example, `2025.0`) is immediately deprecated and we'll no longer support it 24 months after the announcement. We might make exceptions to this policy for service security or health reliability issues.
 
 When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. In some cases, we'll announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated.
 
 When customer calls deprecated API endpoint, the response will contain a header:
 
 ```sh
-Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
+Deprecation: date="Fri, 11 Nov 2026 23:59:59 GMT"
 Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated
 ```
 
@@ -225,8 +230,8 @@ The date tells clients when this version was marked as deprecated.
 
 When building your request, consider the following:
 
- * If you do not specify a version, the service will return the initial version that existed before year-based versioning was introduced. If the initial version does not exist, the response will return an HTTP error code `400 - Bad Request`.
- * If the version header is specified but the requested version is unavailable, the response will return an HTTP error code `400 - Bad Request`.
+ * Endpoints in version `2024.0` can be called without specifying the version in the `box-version` header. If no version is specified and the `2024.0` version of the called endpoint does not exist, the response will return an HTTP error code `400 - Bad Request`.
+ * If the `box-version` version header is specified but the requested version does not exist, the response will return an HTTP error code `400 - Bad Request`.
 
 For details, see [versioning errors](g://api-calls/permissions-and-errors/versioning-errors).
 
@@ -235,7 +240,7 @@ When Box deprecates a resource or a property of a resource in the API, the chang
 * Calls that include the deprecated behavior return the response header `Box-API-Deprecated-Reason` and a link to get more information:
 
     ```sh
-    box-version: 2023.0
+    box-version: 2025.0
     Deprecation: version="version", date="date"
     Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated
     ```
@@ -246,4 +251,4 @@ When Box deprecates a resource or a property of a resource in the API, the chang
 
 ## Additional resources
 
-* [API reference](https://developer.box.com/reference/)
+* [API reference](page://reference)

content/guides/api-calls/permissions-and-errors/scopes.md

@@ -325,19 +325,19 @@ The standard OAuth scopes are also supported when downscoping.
 [console]: https://app.box.com/developers/console
 [ui-elements]: https://github.com/box/box-ui-elements
 [pricing]: https://www.box.com/pricing/platform
-[reference]: https://developer.box.com/reference
+[reference]: page://reference
 <!-- i18n-disable localize-links -->
 [at]: g://authentication/tokens
 [security]: g://security
 [jwt]: g://authentication/jwt
-[mu]:page://platform/user-types/#managed-users
+[mu]: page://platform/user-types/#managed-users
 [au]: g://authentication/jwt/as-user
 [uat]: g://authentication/jwt/user-access-tokens
 [appaccess]: g://authentication/jwt/jwt-setup/#application-access
-[appu]:page://platform/user-types/#app-user
+[appu]: page://platform/user-types/#app-user
 <!-- i18n-enable localize-links -->
 [governance]: https://www.box.com/security/governance-and-compliance
 <!-- i18n-disable localize-links -->
 [suppress]: g://api-calls/suppress-notifications
 [ds]: g://authentication/tokens/downscope
-[sa]:page://platform/user-types/#service-account
+[sa]: page://platform/user-types/#service-account

content/guides/api-calls/permissions-and-errors/versioning-errors.md

@@ -11,15 +11,15 @@ Box provides versioning capabilities for selected API endpoints. The version con
 
 API versioning empowers Box to continually enhance its platform, while also offering third-party developers a reliable avenue for feature updates and deprecations.
 
-To stay informed about the API modifications, monitor the [Changelog](https://developer.box.com/changelog/) and maintain a current email address in the **App Info** section of the Developer Console.
+To stay informed about the API modifications, monitor the [Changelog](page://changelog) and maintain a current email address in the **App Info** section of the Developer Console.
 
 ## Error examples
 
 When using versioned API calls, you can encounter versioning-related errors. This reference lists the most common cases when errors appear and provides you with examples of such errors.
 
 ## Calling with incorrect `box-version` header
 
-If you call an API using an incorrect `box-version` header, the API will respond with an `HTTP error code 400 - Bad Request` error and provide the supported versions in the response message. 
+If you call an API using an incorrect `box-version` header, the API will respond with an `HTTP error code 400 - Bad Request` error and provide the supported versions in the response message.
 
 The response will include one of the following status messages in `message` field:
 
@@ -53,12 +53,12 @@ Box documentation specifies API URLs. For instance, the Sign Requests endpoints
 When you use an API version that Box has marked as deprecated, the API will respond as usual. Additionally, it will append a `Deprecation` header, stating the deprecation date. For example:
 
 ```sh
-Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
+Deprecation: date="Fri, 11 Nov 2026 23:59:59 GMT"
 Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated
 ```
 
 You should monitor API responses to verify if the `Deprecation` header is present to accordingly plan the transition to a new API version.
 
 ## Calling a non-existent version
 
-If you attempt to use an outdated API version, such as `2023.0` which has reached its end-of-life, the response will return an `HTTP error code 404 - Not Found`. See [Calling an incorrect API version in the URL](#calling-an-incorrect-api-version-in-the-url) for more information.
+If you attempt to use an outdated API version, such as `2025.0` which has reached its end-of-life, the response will return an `HTTP error code 404 - Not Found`. See [Calling an incorrect API version in the URL](#calling-an-incorrect-api-version-in-the-url) for more information.

content/guides/applications/app-types/custom-apps.md

@@ -66,6 +66,6 @@ Custom Apps may require approval before use.
 
 [oauth2]: g://authentication/oauth2
 [jwt]: g://authentication/jwt
-[cc]: g://authentication/client-credentials/
-[uie]: g://embed/ui-elements/
+[cc]: g://authentication/client-credentials
+[uie]: g://embed/ui-elements
 [users]: g;//getting-started/user-types/#managed-users/

content/guides/applications/app-types/index.md

@@ -35,6 +35,6 @@ create.
 [devtoken]: g://authentication/tokens/developer-tokens
 [custom-apps]: g://applications/app-types/custom-apps
 [custom-skills]: g://applications/app-types/custom-skills
-[ccg]: g://authentication/client-credentials/
-[laa]: g://applications/app-types/limited-access-apps/
+[ccg]: g://authentication/client-credentials
+[laa]: g://applications/app-types/limited-access-apps
 [insights]: https://support.box.com/hc/en-us/articles/20738406915219-Platform-Insights

content/guides/applications/app-types/limited-access-apps.md

@@ -12,15 +12,15 @@ with a [limited number of endpoints][limited].
 
 ## Authentication methods
 
-Limited Access Apps only support App Token authentication. 
+Limited Access Apps only support App Token authentication.
 
 <CTA to='g://authentication/app-token'>
   Learn more about App Tokens
 </CTA>
 
 ## When to use
 
-A Limited Access App is best used when the application: 
+A Limited Access App is best used when the application:
 
 - wants to use Box View or only Box's preview services
 - only needs to access a [limited number of endpoints][limited]
@@ -33,11 +33,11 @@ A Limited Access App is best used when the application:
 
 ## Approval
 
-Limited Access Apps may require approval before use. 
+Limited Access Apps may require approval before use.
 
 <CTA to='g://authorization/limited-access-approval'>
   Learn how to approve Limited Access Apps
 </CTA>
 
-[bv]: g://embed/box-view/
+[bv]: g://embed/box-view
 [limited]: g://authentication/app-token/endpoints

content/guides/applications/web-app-integrations/configure.md

@@ -143,8 +143,8 @@ Center. Follow the [Integrations][integrations] guide for more details.
 
 [ca]: g://applications/app-types/custom-apps
 [pu]: g://applications/web-app-integrations/types
-[uid]:page://platform/appendix/locating-values/#user-ids
-[fid]:page://platform/appendix/locating-values/#content-ids
+[uid]: page://platform/appendix/locating-values/#user-ids
+[fid]: page://platform/appendix/locating-values/#content-ids
 [code]: g://authentication/oauth2/without-sdk/#3-user-grants-application-access
 [custom-oauth2]: g://authentication/oauth2/oauth2-setup
 [devconsole]: https://app.box.com/developers/console

content/guides/authentication/best-practices.md

@@ -84,5 +84,5 @@ enhancements.
 Developer Tokens should only be used for development or testing purposes and
 never in production.
 
-[downscope]: g://authentication/tokens/downscope/
-[revoke]: g://authentication/tokens/revoke/
+[downscope]: g://authentication/tokens/downscope
+[revoke]: g://authentication/tokens/revoke

content/guides/authentication/client-credentials/index.md

@@ -80,7 +80,7 @@ This error indicates either:
 
 - the client ID and client secret passed are incorrect or are not for the same application,
 
-- the `box_subject_id` cannot be used based on the selected [application access][aa]. 
+- the `box_subject_id` cannot be used based on the selected [application access][aa].
 
 <Message warning>
 
@@ -105,8 +105,8 @@ Once you make changes to the app settings, don't forget to [reauthorize][reauth]
 <!-- i18n-disable localize-links -->
 
 [devconsole]: https://app.box.com/developers/console
-[accesstoken]: e://post-oauth2-token/
-[sa]: page://platform/user-types/#service-account/
+[accesstoken]: e://post-oauth2-token
+[sa]: page://platform/user-types/#service-account
 [auth]: g://authorization
 [aa]: g://authentication/client-credentials/client-credentials-setup/#application-access
 [reauth]: g://authorization/custom-app-approval#re-authorization-on-changes

content/guides/authentication/oauth2/without-sdk.md

@@ -318,11 +318,11 @@ To learn how to use an Access Token visit our guide on [Making API calls][apic].
 
 <!-- i18n-disable localize-links -->
 
-[auth]: e://get-authorize/
+[auth]: e://get-authorize
 [ci]: e://get-authorize/#param-client_id
 [re]: e://get-authorize/#param-redirect_uri
 [co]: e://get-authorize/#param-response_type
 [st]: e://get-authorize/#param-state
 [thirty]: g://api-calls/permissions-and-errors/expiration
-[at]: e://post-oauth2-token/
-[apic]: g://api-calls/
+[at]: e://post-oauth2-token
+[apic]: g://api-calls