[Cognitive Services] October Preview ARM API #37813

CarlOchs · 2025-09-29T16:23:05Z

ARM (Control Plane) API Specification Update Pull Request

Tip

Overwhelmed by all this guidance? See the Getting help section at the bottom of this PR description.

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.

Purpose of this PR

What's the purpose of this PR? Check the specific option that applies. This is mandatory!

New resource provider.
New API version for an existing resource provider. (If API spec is not defined in TypeSpec, the PR should have been created in adherence to OpenAPI specs PR creation guidance).
Update existing version for a new feature. (This is applicable only when you are revising a private preview API version.)
Update existing version to fix OpenAPI spec quality issues in S360.
Convert existing OpenAPI spec to TypeSpec spec (do not combine this with implementing changes for a new API version).
Other, please clarify:
- edit this with your clarification

Due diligence checklist

To merge this PR, you must go through the following checklist and confirm you understood
and followed the instructions by checking all the boxes:

I confirm this PR is modifying Azure Resource Manager (ARM) related specifications, and not data plane related specifications.
I have reviewed following Resource Provider guidelines, including
ARM resource provider contract and
REST guidelines (estimated time: 4 hours).
I understand this is required before I can proceed to the diagram Step 2, "ARM API changes review", for this PR.
A release plan has been created. If not, please create one as it will help guide you through the REST API and SDK creation process.

Additional information

Viewing API changes

For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.

Suppressing failures

If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the
suppressions guide to get approval.

Getting help

First, please carefully read through this PR description, from top to bottom. Please fill out the Purpose of this PR and Due diligence checklist.
If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
To understand what you must do next to merge this PR, see the Next Steps to Merge comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure
and https://aka.ms/ci-fix.
For help with ARM review (PR workflow diagram Step 2), see https://aka.ms/azsdk/pr-arm-review.
If the PR CI checks appear to be stuck in queued state, please add a comment with contents /azp run.
This should result in a new comment denoting a PR validation pipeline has started and the checks should be updated after few minutes.
If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.
For guidance on SDK breaking change review, refer to https://aka.ms/ci-fix.

github-actions · 2025-09-29T16:23:22Z

Next Steps to Merge

✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.

Comment generated by summarize-checks workflow run.

github-actions · 2025-09-29T16:25:28Z

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.CognitiveServices
Go	sdk/resourcemanager/cognitiveservices/armcognitiveservices
Java	com.azure.resourcemanager:azure-resourcemanager-cognitiveservices
JavaScript	@azure/arm-cognitiveservices

ravimeda · 2025-09-30T14:28:49Z

      "202": {

Though some RPs use 202, the recommendation is to 201 for long-running PUTs.

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:81 in 719a515. [](commit_id = 719a515, deletion_comment = False)

ravimeda · 2025-09-30T14:31:07Z

  "delete": {

Curious if you support synchronous delete? If so, include a 200 (OK) response. #Closed

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:6047 in 719a515. [](commit_id = 719a515, deletion_comment = False)

ravimeda · 2025-09-30T14:35:35Z

  "delete": {

Similar to the other comment - do you want to support sync delete? #Closed

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:5302 in 719a515. [](commit_id = 719a515, deletion_comment = False)

ravimeda · 2025-09-30T14:35:52Z

    "summary": "The GET API for retrieveing a single outbound rule of the managed network associated with the cognitive services account.",

Typo #Closed

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:5370 in 719a515. [](commit_id = 719a515, deletion_comment = False)

ravimeda · 2025-09-30T14:39:26Z

        "$ref": "./examples/ManagedNetwork/deleteRuleV2.json"

I do not see this folder yet. Please push the changes. #Closed

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:5362 in 719a515. [](commit_id = 719a515, deletion_comment = False)

ravimeda · 2025-09-30T14:46:25Z

    "x-ms-long-running-operation": true,

Long-running PUT must support 201 (Created). #Closed

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:5815 in 719a515. [](commit_id = 719a515, deletion_comment = False)

ravimeda

🕐

ravimeda

aditya30394 · 2025-10-14T21:10:07Z

      "200": {
same as above

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:1744 in 912f691. [](commit_id = 912f691, deletion_comment = False)

Yes, both the resume and pause APIs use POST and are synchronus

fareedmabrouk · 2025-10-14T21:26:52Z

      "200": {
is this a synchronus delete?

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:5332 in 5290c6c. [](commit_id = 5290c6c, deletion_comment = False)

Addressed

fareedmabrouk · 2025-10-14T21:27:36Z

    "x-ms-pageable": {
this for a post?

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:6285 in 5290c6c. [](commit_id = 5290c6c, deletion_comment = False)

Addressed

* Copy files from preview/2025-07-01-preview Copied the files in a separate commit. This allows reviewers to easily diff subsequent changes against the previous spec. * Update version to preview/2025-10-01-preview Updated the API version from preview/2025-07-01-preview to preview/2025-10-01-preview. * Added tag for 2025-10-01-preview in readme file * Add NMS v2 to cogsvc swagger. * Update parameter casing. * Update api versions in examples. * Update NMS parameter properties * Copy over pre-approved suppressions from previous API version. * Add suppressions for NMS v2 swagger additions. * Remove unneeded properties, add provision route * Update accountNameParameter casing. * Update api version in swagger to 2025-10-01-preview. * Consistent naming for package tag in readme. * Prettier gate formatting fix. * Retrigger pipelines * Add summary for outbound rule operation. --------- Co-authored-by: Mike Harder <mharder@microsoft.com>

* Add agentic application to cog services swagger. * Address pipelines. * Fix spellcheck pipeline.

* feat(cognitiveservices): Add deployment pause/resume APIs and service tier management - Add serviceTier enum property to DeploymentProperties (Default, Priority) - Add deploymentState enum property to DeploymentProperties (Running, Paused) - Add POST /deployments/{deploymentName}/pause endpoint for pausing deployments - Add POST /deployments/{deploymentName}/resume endpoint for resuming deployments - Create API examples for pause and resume operations - Update existing deployment examples to include new properties - Add comprehensive descriptions with usage guidance and SKU restrictions - Document HTTP 423 behavior for paused deployments - Mark both operations as idempotent This enables customers to control deployment processing priority through service tiers and pause/resume deployment inferencing for cost optimization and resource management. * need to add pattern for lint errors * deploymentNameForActionParameter

* Update API spec for the Safety provider Get and List APIs * Add webhook URL to the spec * fix duplicate error * address NDA issue * update safetyprovider urls to subscription level * add susbscription level safety provider * Add test connection and sub rai policy * remove unused changes * update format * Update testRaiExternalSafetyProvider endpoint path * update policy name parameter in subscription level * Club together the tags for all safety provider apis * fix prettier error * Fix swagger error * Fix validation errors * Add suppressions --------- Co-authored-by: tparuchuri <tparuchuri@example.com> Co-authored-by: Tejaswi Paruchuri <86433817+Tparuchuri@users.noreply.github.com> Co-authored-by: CJ Ochs <carlochs@microsoft.com>

* Adding spec json for RaiIfcRule get * Add IfcRule and Tool Label feature to cogsvc control plane * Update raiToolLabelNameParameter * Update for RaiIfcRule and RaiToolLabel * Fix required ifcRuleName * Add suppressions for AvoidAdditionalProperties LintDiff flag * Add "hitl" as valid word * Update Enums for source and action in RaiPolicyContentFilter * Remove RaiIfcRule * Add 'hitl' to cspell.yaml dictionary --------- Co-authored-by: CJ Ochs <carlochs@microsoft.com> Co-authored-by: CJ Ochs <111904639+CarlOchs@users.noreply.github.com>

fareedmabrouk · 2025-10-14T21:41:02Z

      "200": {
is this a synchronus delete?

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:5332 in 5290c6c. [](commit_id = 5290c6c, deletion_comment = False)

Addressed

fareedmabrouk · 2025-10-14T21:42:07Z

    "x-ms-pageable": {
this for a post?

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:6285 in 5290c6c. [](commit_id = 5290c6c, deletion_comment = False)

Addressed

fareedmabrouk · 2025-10-14T21:42:39Z

        "description": "OK"
is this a sync delete

Refers to: specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json:6520 in 5290c6c. [](commit_id = 5290c6c, deletion_comment = False)

Addressed

psah434 · 2025-10-15T17:44:51Z

specification/cognitiveservices/resource-manager/readme.md

+input-file:
+  - Microsoft.CognitiveServices/preview/2025-10-01-preview/cognitiveservices.json
+suppressions:
+  - code:  ProvisioningStateMustBeReadOnly


are you sure you need these? I dont see this in any other RT?

this one is necessary, it's for the new applications routes that trigger the lintdiff check for provisioningstate must be readonly despite already having it set.

can this be specific to the routes

it is specific to the routes with each path, did you have a different path in mind?

psah434 · 2025-10-15T17:44:59Z

specification/cognitiveservices/resource-manager/readme.md

+      - $.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/applications/{name}"].get.responses.200.schema
+      - $.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/applications/{name}"].put.responses.200.schema
+      - $.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/applications/{name}"].put.responses.201.schema
+  - code:  ProvisioningStateMustBeReadOnly


same as above

also necessary for the new project applications routes, lintdiff trips otherwise

can this be more specific

same as above, did you have a different path in mind? it's already applied to each route individually where necessary

psah434 · 2025-10-15T17:45:48Z

specification/cognitiveservices/resource-manager/readme.md

+      - $.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/applications/{appName}/deployments/{deploymentName}"].get.responses.200.schema
+      - $.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/applications/{appName}/deployments/{deploymentName}"].put.responses.200.schema
+      - $.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/applications/{appName}/deployments/{deploymentName}"].put.responses.201.schema
+  - code: ArmResourcePropertiesBag


can you elaborate?

machinelearningservices manifest has the same definition since the managed workspace is essentially being "copied" over:

azure-rest-api-specs/specification/machinelearningservices/resource-manager/Microsoft.MachineLearningServices/preview/2025-07-01-preview/workspaceRP.json

Lines 6271 to 6287 in d7e4f9f

"OutboundRuleBasicResource": {

"required": [

"properties"

],

"type": "object",

"allOf": [

{

"$ref": "../../../../../common-types/resource-management/v3/types.json#/definitions/Resource"

}

],

"properties": {

"properties": {

"description": "Outbound Rule for the managed network of a machine learning workspace.",

"$ref": "#/definitions/OutboundRule"

}

}

},

"OutboundRuleBasicResource": { "required": [ "properties" ], "type": "object", "allOf": [ { "$ref": "../../../../../common-types/resource-management/v3/types.json#/definitions/Resource" } ], "properties": { "properties": { "description": "Outbound Rule for the managed network of a machine learning workspace.", "$ref": "#/definitions/OutboundRule" } } },

psah434 · 2025-10-15T17:47:09Z

specification/cognitiveservices/resource-manager/readme.md

+    reason: This API is copied from Machine Learning Services RP where this behavior is already established.
+    where:
+      - $.definitions.OutboundRuleBasicResource
+  - code: AvoidAdditionalProperties


in a previous api version, this is there for a different RT. is this a similar pattern?

the managednetworksettings is unique to the 2025-10-01-preview api version, so it's a new pattern

CarlOchs requested review from MattGal and rkuthala as code owners September 29, 2025 16:23

CarlOchs added the NotReadyForReview <valid label in PR review process>It is in draft for swagger or not swagger PR label Sep 29, 2025

microsoft-github-policy-service bot added the Cognitive Services label Sep 29, 2025

github-actions bot added brownfield Brownfield services will soon be required to convert to TypeSpec. See https://aka.ms/azsdk/typespec. ARMReview resource-manager WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required labels Sep 29, 2025

github-actions bot added new-api-version SuppressionReviewRequired labels Sep 30, 2025

fmabroukmsft removed the NotReadyForReview <valid label in PR review process>It is in draft for swagger or not swagger PR label Sep 30, 2025

ravimeda requested changes Sep 30, 2025

View reviewed changes

ravimeda added ARMChangesRequested and removed WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required labels Sep 30, 2025

ravimeda approved these changes Sep 30, 2025

View reviewed changes

ravimeda added ARMSignedOff <valid label in PR review process>add this label when ARM approve updates after review and removed ARMChangesRequested labels Sep 30, 2025

fmabroukmsft added the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Oct 13, 2025

fmabroukmsft force-pushed the carlochs/cogsvc-2025-10-01-preview branch from 0e4611b to 1f9710d Compare October 14, 2025 21:24

CarlOchs and others added 7 commits October 14, 2025 17:36

Base 2025-10-01-preview on 2025-09-01 stable

edaccf9

Update api-version in examples.

69c304e

Add agentic application to cog services swagger. (#37849)

56370bd

* Add agentic application to cog services swagger. * Address pipelines. * Fix spellcheck pipeline.

fmabroukmsft force-pushed the carlochs/cogsvc-2025-10-01-preview branch from 1f9710d to 31ac723 Compare October 14, 2025 21:37

Address synchronous to asynchronous routes and unneeded pagination.

c6426eb

fmabroukmsft force-pushed the carlochs/cogsvc-2025-10-01-preview branch from 31ac723 to c6426eb Compare October 14, 2025 21:41

CarlOchs removed the ARMChangesRequested label Oct 14, 2025

github-actions bot added the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Oct 14, 2025

psah434 added ARMChangesRequested ARMSignedOff <valid label in PR review process>add this label when ARM approve updates after review and removed WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required ARMChangesRequested labels Oct 14, 2025

CarlOchs added the PublishToCustomers Acknowledgement the changes will be published to Azure customers. label Oct 15, 2025

psah434 reviewed Oct 15, 2025

View reviewed changes

CarlOchs requested a review from psah434 October 16, 2025 15:29

psah434 added the Approved-Suppression label Oct 16, 2025

	"OutboundRuleBasicResource": {
	"required": [
	"properties"
	],
	"type": "object",
	"allOf": [
	{
	"$ref": "../../../../../common-types/resource-management/v3/types.json#/definitions/Resource"
	}
	],
	"properties": {
	"properties": {
	"description": "Outbound Rule for the managed network of a machine learning workspace.",
	"$ref": "#/definitions/OutboundRule"
	}
	}
	},

[Cognitive Services] October Preview ARM API #37813

Are you sure you want to change the base?

[Cognitive Services] October Preview ARM API #37813

Conversation

CarlOchs commented Sep 29, 2025

ARM (Control Plane) API Specification Update Pull Request

PR review workflow diagram

Purpose of this PR

Due diligence checklist

Additional information

Getting help

Uh oh!

github-actions bot commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Next Steps to Merge

Uh oh!

github-actions bot commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Change Check

Uh oh!

ravimeda commented Sep 30, 2025

Uh oh!

ravimeda commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda left a comment

Choose a reason for hiding this comment

Uh oh!

ravimeda left a comment

Choose a reason for hiding this comment

Uh oh!

aditya30394 commented Oct 14, 2025

Uh oh!

fareedmabrouk commented Oct 14, 2025

Uh oh!

fareedmabrouk commented Oct 14, 2025

Uh oh!

fareedmabrouk commented Oct 14, 2025

Uh oh!

fareedmabrouk commented Oct 14, 2025

Uh oh!

fareedmabrouk commented Oct 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

github-actions bot commented Sep 29, 2025 •

edited

Loading

github-actions bot commented Sep 29, 2025 •

edited

Loading

ravimeda commented Sep 30, 2025 •

edited

Loading

ravimeda commented Sep 30, 2025 •

edited

Loading

ravimeda commented Sep 30, 2025 •

edited

Loading

ravimeda commented Sep 30, 2025 •

edited

Loading

ravimeda commented Sep 30, 2025 •

edited

Loading