--- title: "API support matrix" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{API support matrix} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- foundryR separates Microsoft Foundry endpoint families because their paths, token audiences, and supported authentication differ. This page is a reference for package behavior, not a Microsoft support statement. ## Endpoint and authentication families | Family | Endpoint shape | Token audience | API key support in foundryR | |---|---|---|---| | Resource endpoint | `https://.openai.azure.com` | `https://cognitiveservices.azure.com` | The resource API key works for every resource family tested. | | Project endpoint | `https://.services.ai.azure.com/api/projects/` | `https://ai.azure.com` | On the default project, the resource API key worked for responses, agent-backed responses, conversations, files, vector stores, and agents. Project evaluations need a Microsoft Entra ID token. | | Speech endpoint | Speech resource endpoint | Speech token or Cognitive Services token | Speech API keys are supported by `foundry_set_speech_key()`. | | Content Safety endpoint | Content Safety resource endpoint | `https://cognitiveservices.azure.com` for operations whose reference documents OAuth2 | API keys are supported. Token support depends on the operation. | | Legacy deployment route | `https://.openai.azure.com/openai/deployments//...` | `https://cognitiveservices.azure.com` | The resource API key works. Use `api = "deployment"` where a classic deployment path is required. | Configure resource and project token providers separately when you use Microsoft Entra ID. The two audiences are different, so one cached token should not be reused for both endpoint families. ```r foundry_set_token_provider( foundry_token_azure_cli("https://cognitiveservices.azure.com"), scope = "resource" ) foundry_set_token_provider( foundry_token_azure_cli("https://ai.azure.com"), scope = "project" ) ``` ## OpenAI-compatible and project surfaces | Surface | Endpoint support | foundryR route behavior | Notes | |---|---|---|---| | Chat completions | Resource endpoint | Resource route | v1 chat-completions path. | | Responses | Resource and project endpoints | Resource route by default; pass `project_endpoint =` or call `foundry_set_route("project")` for project responses | Agent-backed responses always use the project endpoint. | | Embeddings | Resource endpoint | Resource route | `model =` is a deployment name. | | Models | Resource endpoint | Resource route | Lists models available to the resource, not your deployments. | | Files | Resource and project endpoints | Resource route by default; project route when requested | Server-side agents search files and vector stores created on the project endpoint. | | Vector stores | Resource and project endpoints | Resource route by default; project route when requested | Use the same endpoint for store creation and project-agent file search. | | Batches | Resource endpoint | Resource route | Batch jobs need a Global Batch or Data Zone Batch deployment type. | | Conversations | Project endpoint only | Always project route | `foundry_conversation_*()` functions require a project endpoint. | | Agents | Project endpoint only | Always project route | Includes agent definitions, versions, and agent-backed responses. | | Evaluations | Resource and project endpoints | Resource route for OpenAI graders on existing columns; project route for built-in evaluators, model targets, agent targets, and stored responses | Project evaluations need Microsoft Entra ID. foundryR stops with guidance before sending a key-authenticated project evaluation. | | Images | Resource endpoint | Image endpoint helpers, or the main resource endpoint as fallback | Current image generation uses v1 preview image paths. | | Audio | Speech endpoint, resource v1 audio route, or legacy deployment route | Speech fast transcription is the default for `foundry_transcribe()` | Whisper deployments use `service = "openai", api = "deployment"`. | | Video | None | Defunct functions | Azure retires its last Sora model on 2026-10-15, so foundryR stops instead of wrapping the retired video job API. | ## Evaluations Resource evaluations work with API keys when the graders operate on existing dataset columns, such as string checks and OpenAI judge graders. Project evaluations are selected when the run uses built-in Azure AI evaluators, a model target, an agent target, or stored response IDs. Built-in evaluator names include values such as `builtin.coherence`, `builtin.task_adherence`, and `builtin.intent_resolution`; their judge deployment is passed in `initialization_parameters`, commonly as `deployment_name`. Project evaluations require a Microsoft Entra ID token with the project audience. Configure the project token provider before submitting those runs. API-key requests to project evaluations returned 403 in live testing, so foundryR reports the requirement before it sends the request. ## Speech family `foundry_transcribe()` defaults to Speech fast transcription. That default does not use a model or deployment name, and the returned `model` column is `NA`. MAI-Transcribe and LLM Speech enhanced mode are opt-in, preview or region-limited paths. Supplying `model = "mai-transcribe-2"`, `prompt =`, `transcribe_style =`, or `enhanced = TRUE` selects enhanced mode for Speech transcription. Speech translation also requires LLM Speech enhanced mode. When a region does not support enhanced mode, foundryR preserves the service message and adds region guidance. OpenAI-compatible audio calls use `service = "openai"`. Classic Azure `whisper` deployments require the legacy deployment route, and Azure `whisper` version 001 retires on 2026-12-15: ```r foundry_translate_audio( "speech.wav", service = "openai", model = "whisper", api = "deployment" ) ``` ## Content Safety surfaces | Surface | API version | Lifecycle in foundryR | Authentication in foundryR | |---|---|---|---| | Text moderation | `2024-09-01` | Stable reference track | API key or supported resource token | | Image moderation | `2024-09-01` | Stable reference track | API key or supported resource token | | Protected material in text | `2024-09-01` | Stable reference track | API key or supported resource token | | Prompt Shields | `2024-09-01` | Stable reference track | API key | | Blocklists | `2024-09-01` | Stable reference track | API key | | Groundedness | `2024-09-15-preview` | Preview and region-limited | API key | | Protected code | `2024-09-15-preview` | Preview | API key | | Image-with-text moderation | `2024-09-15-preview` | Preview | API key | | Task adherence | `2025-09-15-preview` | Preview | API key | ## Current omissions The Microsoft Foundry project reference also exposes connections, datasets, deployments, evaluation taxonomies and rules, evaluator catalogs, indexes, insights, red-team schedules and runs, schedules, memory stores, and agent containers. foundryR does not wrap those surfaces in this release. ## Compatibility policy 1. Resource v1 is the default for OpenAI-compatible operations that can run on a resource. 2. Project APIs are selected explicitly, except for conversations, agents, agent-backed responses, and project-only evaluation scenarios. 3. Preview operations remain experimental and may change in a minor release when Microsoft changes their contract. 4. Legacy deployment routes are compatibility fallbacks. Use `api = "deployment"` for classic deployments such as Azure `whisper`. 5. Recorded fixtures test known contracts without network access. Maintainers should run credentialed contract tests separately before each release.