---
title: "Create Canary Deploy"
method: POST
path: "/ai/assistants/{assistant_id}/canary-deploys"
tags: ["Assistants"]
---

# Create Canary Deploy

`POST /ai/assistants/{assistant_id}/canary-deploys`

Endpoint to create a canary deploy configuration for an assistant.

Creates a new canary deploy configuration with multiple version IDs and their traffic
percentages for A/B testing or gradual rollouts of assistant versions.

## Path parameters

- `assistant_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CanaryDeployRequest — Create/update request body. Accepts: - ``rules`` — canonical ordered list of routing rules
  - `rules` RuleInput[]
    - `match` Clause[]
      - `attribute` string, required — Attribute name from the routing context
      - `operator` 'in' | 'not_in' | 'starts_with', required
      - `values` string[], required
    - `serve` Serve, required — What a rule serves when matched. Exactly one of: - ``version_id`` — serve a specific version - ``rollout`` — weighted random across versions; weights must sum to less than 100, with the leftover routing to the main version
      - `version_id` string
      - `rollout` RolloutSlot[]
        - `version_id` string, required
        - `weight` number, required

## Response `200`

Successful Response

- CanaryDeployResponse — Response shape. Always carries ``rules`` (canonical).
  - `assistant_id` string, required
  - `rules` RuleOutput[], required
    - `match` Clause[]
      - `attribute` string, required — Attribute name from the routing context
      - `operator` 'in' | 'not_in' | 'starts_with', required
      - `values` string[], required
    - `serve` Serve, required — What a rule serves when matched. Exactly one of: - ``version_id`` — serve a specific version - ``rollout`` — weighted random across versions; weights must sum to less than 100, with the leftover routing to the main version
      - `version_id` string
      - `rollout` RolloutSlot[]
        - `version_id` string, required
        - `weight` number, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400` — Bad Request / Validation Failed (10015). Invalid, duplicate, empty, malformed, or overlong Idempotency-Key headers are rejected by Edge with HTTP 400 and error code 10015.
- `409` — A request with the same Idempotency-Key is still being processed (10036). Retry later with the same key and request.
- `413` — Payload Too Large. A request sent with an Idempotency-Key whose body exceeds the endpoint's Edge replay-protection limit (256 KB) is rejected before it reaches the service. Requests sent without the header are not subject to this limit.
- `422` — Validation Error. Reusing an Idempotency-Key with a different request body also returns 422 with error code 10027.
- `503` — Service unavailable (10016), including unavailable Edge idempotency protection for a keyed request.

## Changes

> 78 revisions in range; 1 not diffed.

- **2026-09-22** `9621f6123ebc` — 2 warning
  - added the new `10011` enum value to the `errors/items/code` response property for the response status `409`
  - added the new `domain_graduation_limit_exceeded` enum value to the `errors/items/code` response property for the response status `409`
- **2026-09-16** `a6a61a29ecdd` — 1 breaking, 1 warning, 6 info
  - the response's body type changed from `object` to no type for status `422`
  - removed the optional property `detail` from the response with the `422` status
  - added the new optional `header` request parameter `Idempotency-Key`
  - added `#/components/schemas/HTTPValidationError, #/components/schemas/inference-embedding_ErrorResponse` to the response body `anyOf` list for the response status `422`
  - …4 more

[Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/assistants/:assistant_id/canary-deploys/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/950384d11a37?raw)