Introduction

Use the Microsoft Foundry REST API to create and manage project-scoped resources from any HTTP client. Start here to understand authentication, base URLs, versioning, preview headers, wire formats, and the client SDKs that map to the same API surface.

Making requests

Authentication

Authenticate each request with either a bearer token or an API key.

For Microsoft Entra ID, request a token for the https://ai.azure.com/.default scope.

export FOUNDRY_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://YOUR_ENDPOINT/api/projects/YOUR_PROJECT_NAME/agents?api-version=2025-05-01" \
  -H "Authorization: Bearer ${FOUNDRY_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Base URL

Build project-scoped requests from this base pattern:

https://YOUR_ENDPOINT/api/projects/YOUR_PROJECT_NAME

• YOUR_ENDPOINT is your Foundry resource endpoint.
• YOUR_PROJECT_NAME is the Project name in that resource.

Append the resource path and the api-version query parameter on every call.

API versioning

API versioning

The Foundry API uses a single version identifier. Pass it as a query parameter on every request to non-OpenAI endpoints.

Preview features

Preview capabilities within the v1 API surface are gated by the Foundry-Features request header (e.g., Foundry-Features: Agents.CodeAgents=V1Preview) rather than by a separate API version.

Foundry-Features: HostedAgents=V1Preview

Request and response format

JSON is the default wire format.

Set Content-Type only when you send a body. Use Accept: text/event-stream only for endpoints that document server-sent events.

Client SDKs

Use REST directly, or start from a language SDK when you want typed models, authentication helpers, and a more idiomatic client surface.

See the SDK overview for language-specific reference links.

Troubleshooting

Debugging requests

Log enough metadata to trace failures across services and retries.

• x-request-id: service-generated request identifier
• x-ms-client-request-id: client-supplied correlation identifier
• Server-Timing: optional processing details on some operations

For failed requests, log the full URL, status code, x-request-id, and x-ms-client-request-id. Reuse a client-generated request ID across retries so you can correlate a full attempt chain.

Error handling

Expect structured JSON errors from the API. Handle them consistently, log correlation IDs, and treat status codes as part of the contract.

Error envelope

Most errors use this shape:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "target": "field_name",
    "details": []
  }
}

Use error.code for branching logic when an operation documents stable codes. Use message for diagnostics, not for machine parsing.

Status codes

Correlation IDs

Every failed request should capture x-request-id. This is the fastest way to escalate an issue to support or an internal service owner. If you generate x-ms-client-request-id on the client, log that value too so you can connect retries and downstream logs.

Common error patterns

Authentication failures usually show up as 401 or 403. Check whether you sent the correct header, requested the right Entra scope, and targeted the intended Project.

Validation failures usually show up as 400 or 422. Inspect error.target and any entries in error.details before retrying.

Transient failures usually show up as 429, 500, or 503. These are the cases where retries help.

Rate limits

Microsoft Foundry can enforce limits at more than one layer. A request can hit a per-resource budget, such as requests per minute or concurrency, or a broader per-subscription or per-region quota for constrained preview capacity.

What to expect

When you exceed a limit, the service returns 429 Too Many Requests. If Retry-After is present, wait exactly that long before sending the next attempt.

Retry-After: 12

If the response includes rate-limit metadata, log it with the failure. Common headers can include values such as a total limit, remaining budget, or reset time.

Retry strategy

Use exponential backoff with jitter when Retry-After is absent.

1. Start with a short base delay.
2. Exponentially increase the delay after each 429.
3. Add jitter so many clients do not retry at the same instant.
4. Stop after a bounded number of attempts.

A good retry loop also keeps requests idempotent where possible. If an operation is not safe to replay, persist state before you retry or switch to an application-level recovery path.

Streaming and pagination

Some Microsoft Foundry operations stream incremental output. List operations can also split results across pages. Handle both contracts explicitly in your client.

Streaming with server-sent events

To receive incremental output, send Accept: text/event-stream and keep the connection open until you receive a terminal event or the [DONE] sentinel.

Accept: text/event-stream

Each SSE event arrives as a block separated by a blank line.

event: response.output_text.delta
data: {"delta":"Hello"}

event: done
data: [DONE]

Parse the stream incrementally instead of waiting for the full response body. Treat [DONE] as the terminal marker, then close the connection cleanly.

Reconnection strategy

SSE connections can drop because of network timeouts, client restarts, or proxies. If the operation is retry-safe, reconnect with exponential backoff and resume from application state when the endpoint supports it. If the operation is not safe to replay, surface a partial result and let the caller decide whether to restart.

Pagination

List operations can paginate in a few ways:

• Offset-style parameters such as top and skip
• Continuation tokens
• A nextLink URL in the response body

When nextLink is present, keep requesting pages until it is absent.

{
  "data": [{ "id": "item_1" }, { "id": "item_2" }],
  "nextLink": "https://YOUR_ENDPOINT/api/projects/YOUR_PROJECT_NAME/items?api-version=2025-05-01&skip=2&top=2"
}

Preserve query parameters exactly when following a continuation URL. Do not reconstruct nextLink unless the API explicitly tells you to. That keeps your client compatible with token-based paging and future server-side changes.

Backwards compatibility

Expect additive changes between versions, and code defensively.

Breaking changes

• Removing fields, routes, or operations
• Changing response or request types
• Making optional fields required
• Adding new required headers
• Tightening validation rules

Non-breaking changes

• Adding optional fields
• Adding new endpoints
• Adding new enum values
• Clarifying documentation without changing behavior