Merge branch 'main' into DDOC-1131-incorrect-information-client-credentials

Author: superojla

.spelling

@@ -312,3 +312,25 @@ XCode
 embeddings
 GPT-4
 GPT-3
+freeform
+pre-defined
+stringified
+textembedding
+Gecko
+16k
+4k
+200k
+128k
+8k
+1k
+multimodal
+1m
+32k
+2k
+summarization
+GPT-4o
+Anthropic
+GPT-4o-2024-05-13
+text-embedding-ada-002
+params
+GPT-4o-mini

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

@@ -65,9 +65,13 @@ For example, if security issues need addressing in the previously released versi
 Each stable version is supported for a minimum of 12 months. This means that when a new version is released, the previous version becomes deprecated and will be available for use, but no new features will be added.
 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 `404 - Not Found`. For details, see [Versioning Errors](#versioning-errors).
+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](#versioning-errors).
 
-If your request doesn't include a version, then the API defaults to the `V2` Box API version. However, we do not recommend relying on this behavior for adopting deprecated changes. As you update your app, you should specify the API version with every request. By making your app version-aware, you anchor your code to a specific set of features that are guaranteed to behave in the same way for the supported timeframe.
+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.
 
 ## Calling an API version
 
@@ -83,9 +87,31 @@ The client gets a list of all created sign requests and asks for version `2025.0
 
 ## Versioning errors
 
-### Calling an incorrect API version in the URL
+### Calling an incorrect API version in the header
+
+If the API version provided in the `box-version` header is incorrect, the response will return an `HTTP 400 - Bad Request error`.
+The error response will have the following structure:
+
+```json
+{
+  "type": "error",
+  "status": 400,
+  "code": "invalid_api_version",
+  "message":  "Some error message",
+  "context_info": {
+    "conflicts": [
+      "box_version value must be in the format of YYYY.MM"
+    ]
+  },
+  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/versioning-errors/"
+}
+```
+
+The error message will contain information about the error and possible correct values for the `box-version` header. For example:
 
-Box documentation specifies API URLs. For instance, the Sign Requests endpoints are accessed via: `https://api.box.com/2.0/sign_requests/`. If a customer mistakenly makes a call to an incorrect version, such as `https://api.box.com/3.0/sign_requests/`, the response returns an `HTTP error code 404 - Not Found` error.
+ - `The 'box-version' header supports only one header value per request, do not use comas.` - when the header contains multiple values separated by commas.
+ - `Missing required box-version header.` - when the header is missing but required.
+ - `Unsupported API version specified in 'box-version' header. Supported API versions: [LIST_OF_SUPPORTED_VERSIONS_COMA_SEPARATED]` - when the version specified is not supported by the API.
 
 ### Calling a deprecated API
 
@@ -98,10 +124,6 @@ Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated
 
 Customers should monitor API responses and take note when this header appears, signaling the need to plan for the transition to a new API version.
 
-### Calling a nonexistent version
-
-If a customer attempts 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.
-
 ## How Box SDK versioning works
 
 The versioning strategy is only applied to [next generation generated SDKs](https://developer.box.com/sdks-and-tools/#next-generation-sdks).
@@ -192,6 +214,10 @@ Breaking changes in the Box API occur within versioned releases, typically accom
 We use [oasdiff](https://github.com/Tufin/oasdiff/blob/main/BREAKING-CHANGES-EXAMPLES.md) tool to detect most of the possible breaking changes.
 </Message>
 
+## AI agent configuration versioning
+
+[AI agent](g://box-ai/ai-agents) versioning gives the developers more control over model version management and ensures consistent responses. For details, see [AI agent configuration versioning guide](g://box-ai/ai-agents/ai-agent-versioning).
+
 ## Support policy and deprecation information
 
 When new versions of the Box APIs and Box SDKs are released, earlier versions will be retired. Box marks a version as `deprecated` at least 24 months before retiring it. In other words, a deprecated version cannot become end-of-life
@@ -213,12 +239,12 @@ The date tells clients when this version was marked as deprecated.
 
 ## Versioning considerations
 
-When building your request, consider that:
+When building your request, consider the following:
 
-- If you do not specify a version, the service returns a default version that may not be the latest one.
+ - If you do not specify a version, the service will return the initial version—the 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.
 
-    - When the version header is missing, the default resource version is determined by the version in the URL.
-    - When the version header is specified, but the requested version is unavailable, then the response will return an HTTP error code `404 - Not Found`.
+You can check [Versioning Errors](#versioning-errors) for more information.
 
 When Box deprecates a resource or a property of a resource in the API, the change is communicated in one or more of the following ways:
 

content/guides/api-calls/pagination/marker-based.md

@@ -3,6 +3,7 @@ rank: 2
 related_endpoints:
   - get_folders_id_items
   - get_files_id_collaborations
+  - get_folders_id_collaborations
   - get_webhooks
   - get_metadata_templates_enterprise
   - get_recent_items