> ## Documentation Index > Fetch the complete documentation index at: https://docs.together.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a rollout > Creates a rollout in the pending state without shifting traffic. Start the rollout in a separate request after reviewing its strategy and metric gates. ## OpenAPI ````yaml openapi.yaml POST /projects/{projectId}/endpoints/{endpointId}/rollouts openapi: 3.1.0 info: title: Together APIs description: The Together REST API. See https://docs.together.ai for more details. version: 2.0.0 termsOfService: https://www.together.ai/terms-of-service contact: name: Together Support url: https://www.together.ai/contact license: name: MIT url: https://github.com/togethercomputer/openapi/blob/main/LICENSE servers: - url: https://api.together.ai/v1 description: Default environment for APIs - url: https://api-inference.together.ai/v2 description: Optimized environment for inference security: - bearerAuth: [] paths: /projects/{projectId}/endpoints/{endpointId}/rollouts: post: tags: - RolloutService summary: Create a rollout description: >- Creates a rollout in the pending state without shifting traffic. Start the rollout in a separate request after reviewing its strategy and metric gates. operationId: RolloutService_CreateRollout parameters: - name: projectId in: path required: true schema: description: Project identifier. type: string - name: endpointId in: path required: true schema: description: Endpoint identifier. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DE.CreateRolloutRequest' examples: canary: summary: Canary rollout with a metric gate value: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 canary: steps: - traffic: 25 - traffic: 50 - traffic: 100 stepInterval: 300s metrics: - name: router_latency stat: METRIC_STAT_TYPE_PERCENTILE percentile: 95 thresholdCheck: value: 30000 operator: THRESHOLD_OPERATOR_LT window: 300s blueGreen: summary: Blue-green cutover value: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 blueGreen: {} rolling: summary: Rolling replica swap value: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 rolling: {} required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DE.Rollout' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/ErrorData' servers: - url: https://api.together.ai/v2 components: schemas: DE.CreateRolloutRequest: type: object description: >- Strategy, metric gates, timing, and cleanup policy for shifting traffic between two deployments under one endpoint. required: - sourceDeploymentId - targetDeploymentId oneOf: - x-stainless-variantName: Canary required: - canary - x-stainless-variantName: BlueGreen required: - blueGreen - x-stainless-variantName: Rolling required: - rolling properties: sourceDeploymentId: type: string description: Deployment that traffic shifts away from. targetDeploymentId: type: string description: Deployment that traffic shifts toward. canary: allOf: - $ref: '#/components/schemas/DE.CanaryConfig' description: >- Canary rollout strategy configuration. Mutually exclusive with blueGreen and rolling. blueGreen: allOf: - $ref: '#/components/schemas/DE.BlueGreenConfig' description: >- Blue-green rollout strategy configuration. Mutually exclusive with canary and rolling. rolling: allOf: - $ref: '#/components/schemas/DE.RollingConfig' description: >- Rolling rollout strategy configuration. Mutually exclusive with canary and blueGreen. metrics: type: array items: $ref: '#/components/schemas/DE.MetricRule' description: >- Optional metric gates evaluated after each step's soak. Canary only; rejected on rolling and blue-green rollouts. finalSourceReplicas: type: integer description: >- Optional final replica count for the source deployment. Defaults to 0, which drains and stops the source. finalTargetReplicas: type: integer description: >- Optional target replica floor at completion. Must be at least 1 when set; defaults to the source deployment's replica count at create time, or to the source and target deployments' combined replica count when both already stand in the endpoint traffic split after a cancel. The completed target's autoscaling max lands at the landing ceiling, max(this value, the source max, the target's own max); the rollout may lift the target max at first wake, at the first step that needs it, or at completion unless an operator changes max mid-run. The lifted ceiling remains after completion, and PreviewRolloutDefaults reports a coming lift as ROLLOUT_WILL_RAISE_TARGET_MAX. A pre-existing target whose own autoscaling min is higher keeps that floor, reported as FINAL_BELOW_INHERITED_MIN. A target that starts stopped lands exactly at this value; if the source min was higher, PreviewRolloutDefaults reports FINAL_BELOW_SOURCE_MIN. DE.Rollout: type: object description: >- Public view of a rollout resource, including runtime progress and any pause or abort reason. required: - id - endpointId - sourceDeploymentId - targetDeploymentId - strategy - state - createdAt - status properties: id: type: string description: Output only. Unique rollout identifier. readOnly: true endpointId: type: string description: Output only. Endpoint this rollout belongs to. readOnly: true sourceDeploymentId: type: string description: Output only. Deployment that traffic is shifting away from. readOnly: true targetDeploymentId: type: string description: Output only. Deployment that traffic is shifting toward. readOnly: true strategy: enum: - ROLLOUT_STRATEGY_TYPE_ROLLING - ROLLOUT_STRATEGY_TYPE_CANARY - ROLLOUT_STRATEGY_TYPE_BLUE_GREEN type: string description: Output only. Rollout strategy selected at creation. readOnly: true state: enum: - ROLLOUT_STATE_RUNNING - ROLLOUT_STATE_PAUSED - ROLLOUT_STATE_STABILIZING - ROLLOUT_STATE_COMPLETED - ROLLOUT_STATE_PENDING - ROLLOUT_STATE_SYSTEM_PAUSED - ROLLOUT_STATE_CANCELLING - ROLLOUT_STATE_CANCELED - ROLLOUT_STATE_PAUSING type: string description: Output only. High-level rollout lifecycle state. readOnly: true currentStep: type: integer description: >- Output only. Zero-based index of the current step. Unset while PENDING; step 0 is reported explicitly after start. readOnly: true currentTrafficPercent: type: integer description: Output only. Applied percentage of traffic on the target deployment. readOnly: true createdAt: type: string description: Output only. Timestamp when the rollout was created. format: date-time readOnly: true startedAt: type: string description: Output only. Timestamp when the rollout started running. format: date-time readOnly: true completedAt: type: string description: Output only. Timestamp when the rollout reached a terminal state. format: date-time readOnly: true etag: type: string description: Output only. Opaque version tag for optimistic concurrency control. readOnly: true status: allOf: - $ref: '#/components/schemas/DE.RolloutStatus' description: >- Output only. Derived runtime progress, step summary, and pause or abort failure details. readOnly: true pauseInfo: allOf: - $ref: '#/components/schemas/DE.PauseInfo' description: >- Output only. Why and when the rollout was paused. Set while a pause is pending or effective (PAUSING, PAUSED, or SYSTEM_PAUSED) and cleared after resume or abort; while PAUSING, pausedAt records when the pause was requested. readOnly: true ErrorData: type: object required: - error properties: error: type: object properties: message: type: string nullable: false type: type: string nullable: false param: type: string nullable: true default: null code: type: string nullable: true default: null required: - type - message DE.CanaryConfig: type: object description: >- Canary strategy configuration for gradual traffic progression. An empty config uses the default 5, 25, 50, 100 percent ladder; over a frozen traffic-split pair left by cancel, the default ladder is derived at start from the pair's current served share so it begins above it. properties: steps: type: array items: $ref: '#/components/schemas/DE.RolloutStep' description: >- Optional progression steps. Defaults to 5, 25, 50, 100 percent when empty; explicit steps must increase and end at 100 percent. stepInterval: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: >- Optional positive soak between steps. Defaults to 3m if omitted, and grows to cover metric rule windows plus ingestion lag. DE.BlueGreenConfig: type: object properties: {} additionalProperties: false x-stainless-empty-object: true description: >- Blue-green strategy configuration for a single cutover to the target deployment. DE.RollingConfig: type: object properties: {} additionalProperties: false x-stainless-empty-object: true description: >- Rolling strategy configuration for capacity-preserving batches that ramp target replicas up while draining source replicas. DE.MetricRule: type: object description: Metric gate evaluated during a rollout. required: - name oneOf: - x-stainless-variantName: Threshold required: - thresholdCheck - x-stainless-variantName: Regression required: - regressionCheck properties: name: enum: - inflight_requests - router_error_rate - router_latency type: string description: >- Required catalogue key for the metric to gate on. `serving_latency` is retired. stat: enum: - METRIC_STAT_TYPE_AVG - METRIC_STAT_TYPE_PERCENTILE type: string description: >- Aggregation used for the metric. Optional for router_error_rate and inflight_requests; omitted values default to METRIC_STAT_TYPE_AVG. Required for router_latency, where AVG or PERCENTILE may be used. percentile: type: integer description: >- Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. thresholdCheck: allOf: - $ref: '#/components/schemas/DE.ThresholdCheck' description: >- Threshold evaluation criteria. Mutually exclusive with regressionCheck. regressionCheck: allOf: - $ref: '#/components/schemas/DE.RegressionCheck' description: >- Regression evaluation criteria. Mutually exclusive with thresholdCheck. window: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: >- Optional query window for the metric. Defaults to the step soak duration. DE.RolloutStatus: type: object description: Derived runtime progress for a rollout. required: - totalSteps - steps properties: totalSteps: type: integer description: >- Total number of steps in the rollout progression. Always serializes when status is present. condition: allOf: - $ref: '#/components/schemas/DE.RolloutCondition' description: >- Failure detail set when the rollout pauses, system-pauses, or aborts; carries the human-readable reason and structured detail. steps: type: array items: $ref: '#/components/schemas/DE.RolloutStepStatus' description: Per-step rollout execution summaries. updatedAt: type: string description: Timestamp of the most recent progress update. format: date-time conditions: type: array items: $ref: '#/components/schemas/DE.RolloutCondition' description: >- Informational conditions that describe the rollout's current state. Omitted when empty; clients should treat an absent key as an empty list. DE.PauseInfo: type: object description: Pause metadata returned while a rollout is paused. required: - pausedAt properties: reason: type: string description: Human-readable reason recorded when the rollout was paused. pausedAt: type: string description: Timestamp when the rollout was paused. format: date-time DE.RolloutStep: type: object description: One stage of a canary rollout progression. required: - traffic properties: traffic: type: integer description: >- Required percentage of traffic on the target deployment for this step. replicas: type: integer description: Optional explicit target replica count for this step. DE.ThresholdCheck: type: object description: >- Threshold criteria that fail when the target metric violates the configured bound. required: - operator properties: value: type: number description: |- Finite threshold value. Interpreted in the metric's unit: router_error_rate is a ratio in [0, 1], router_latency is milliseconds, and inflight_requests is in-flight requests per ready replica averaged over the rule window. Thresholds that no achievable value could pass, or that every achievable value passes, are rejected at create. Omitting this value is read as 0. Set 0 explicitly for the strictest threshold: nothing at all is tolerated. operator: enum: - THRESHOLD_OPERATOR_GT - THRESHOLD_OPERATOR_GTE - THRESHOLD_OPERATOR_LT - THRESHOLD_OPERATOR_LTE type: string description: Required comparison operator applied to the target metric value. DE.RegressionCheck: type: object description: >- Regression criteria that fail when the target regresses against the source beyond a limit. required: - direction properties: maxRegressionPercent: type: number description: >- Finite maximum allowed regression percentage, greater than or equal to 0. Omitting this value is read as 0. A value of 0 is the strictest budget; any regression fails, and exactly-at-budget passes. direction: enum: - REGRESSION_DIRECTION_HIGHER_IS_WORSE - REGRESSION_DIRECTION_LOWER_IS_WORSE type: string description: >- Required direction that indicates whether higher or lower metric values are worse. DE.RolloutCondition: type: object description: Structured reason a rollout stopped progressing. properties: category: enum: - ROLLOUT_FAILURE_CATEGORY_METRIC_REGRESSION - ROLLOUT_FAILURE_CATEGORY_METRICS_UNAVAILABLE - ROLLOUT_FAILURE_CATEGORY_TARGET_NOT_READY - ROLLOUT_FAILURE_CATEGORY_SOURCE_NOT_DRAINED - ROLLOUT_FAILURE_CATEGORY_HEALTH_REGRESSION - ROLLOUT_FAILURE_CATEGORY_CAPACITY_EXHAUSTED - ROLLOUT_FAILURE_CATEGORY_ROUTING_ERROR - ROLLOUT_FAILURE_CATEGORY_DEPENDENCY_OUTAGE - ROLLOUT_FAILURE_CATEGORY_ABORTED_BY_OPERATOR - ROLLOUT_FAILURE_CATEGORY_INTERNAL - ROLLOUT_FAILURE_CATEGORY_POLICY_INFEASIBLE - ROLLOUT_FAILURE_CATEGORY_UNDER_SERVED - ROLLOUT_FAILURE_CATEGORY_ENTITLEMENT_LAPSED type: string description: Category that classifies why the rollout stopped. message: type: string description: Human-readable explanation for the condition. atStep: type: integer description: Step index where the condition arose. Step 0 serializes explicitly. observedAt: type: string description: Timestamp when the condition was observed. format: date-time metrics: type: array items: $ref: '#/components/schemas/DE.MetricResult' description: >- Metrics observed at the failing gate, enriched with their criteria. Unmeasured rules appear as synthesized rows with verdict METRIC_VERDICT_UNAVAILABLE and no measured values. type: type: string enum: - CapacityLimited description: >- Informational condition type. `CapacityLimited` means the current step advanced partially because full capacity was not placeable. DE.RolloutStepStatus: type: object description: Collapsed execution state for one rollout step. properties: stepIndex: type: integer description: >- Index of this step in the rollout progression. Step 0 serializes explicitly. targetTrafficPercent: type: integer description: >- Target traffic percentage configured for this step. Always serializes for recorded steps. state: enum: - ROLLOUT_STEP_STATE_PENDING - ROLLOUT_STEP_STATE_RUNNING - ROLLOUT_STEP_STATE_PASSED - ROLLOUT_STEP_STATE_FAILED - ROLLOUT_STEP_STATE_PAUSED - ROLLOUT_STEP_STATE_CANCELED - ROLLOUT_STEP_STATE_SKIPPED type: string description: >- Outcome of this step. Finished steps are PASSED, the live step mirrors the rollout state, skipped-over steps are SKIPPED, and unreached steps are PENDING. metrics: type: array items: $ref: '#/components/schemas/DE.MetricResult' description: >- Metric gate results for this step, enriched with criteria and verdict. Unmeasured rules appear as synthesized rows with verdict METRIC_VERDICT_UNAVAILABLE and no measured values. startedAt: type: string description: >- Timestamp when this step's first sub-step ran. Unset for steps no sub-step reached. format: date-time completedAt: type: string description: >- Timestamp when this step finished, was skipped over, or the rollout ended on it. Unset while in progress. format: date-time failureReason: type: string description: Failure reason set only when this step failed. DE.MetricResult: type: object description: >- Observed metric result enriched with rollout rule criteria and the rule's recorded verdict. Unmeasured rules are synthesized with verdict METRIC_VERDICT_UNAVAILABLE and no source or target value. properties: name: type: string description: Metric name as exported to the observability backend. stat: enum: - METRIC_STAT_TYPE_AVG - METRIC_STAT_TYPE_PERCENTILE type: string description: Aggregation used for the metric. percentile: type: integer description: >- Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. check: enum: - METRIC_CHECK_TYPE_THRESHOLD - METRIC_CHECK_TYPE_REGRESSION type: string description: Evaluation form used by the metric rule. sourceValue: type: number description: >- Observed source baseline. Set only for regression checks with a recorded observation; a 0 reading serializes explicitly. targetValue: type: number description: >- Observed target value. Set when the gate recorded an observation; absent on synthesized unavailable results. A 0 reading serializes explicitly. threshold: type: number description: Threshold criteria used when check is METRIC_CHECK_TYPE_THRESHOLD. operator: enum: - THRESHOLD_OPERATOR_GT - THRESHOLD_OPERATOR_GTE - THRESHOLD_OPERATOR_LT - THRESHOLD_OPERATOR_LTE type: string description: Threshold comparison operator. maxRegressionPercent: type: number description: >- Regression percentage limit used when check is METRIC_CHECK_TYPE_REGRESSION. direction: enum: - REGRESSION_DIRECTION_HIGHER_IS_WORSE - REGRESSION_DIRECTION_LOWER_IS_WORSE type: string description: Direction that indicates whether higher or lower values are worse. verdict: enum: - METRIC_VERDICT_PASS - METRIC_VERDICT_BREACHED - METRIC_VERDICT_UNAVAILABLE type: string description: >- Rule decision recorded by the metric gate. Absent when no decision was recorded. failureReason: type: string description: >- Rule-specific failure text. Set only when verdict is METRIC_VERDICT_BREACHED and the gate recorded one. securitySchemes: bearerAuth: type: http scheme: bearer x-bearer-format: bearer x-default: default ````