Skip to main content
POST
Together AI SDK (Python)

Authorizations

Authorization
string
header
default:default
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

projectId
string
required

Project identifier.

endpointId
string
required

Endpoint identifier.

Body

application/json

Strategy, metric gates, timing, and cleanup policy for shifting traffic between two deployments under one endpoint.

sourceDeploymentId
string
required

Deployment that traffic shifts away from.

targetDeploymentId
string
required

Deployment that traffic shifts toward.

canary
object
required

Canary rollout strategy configuration. Mutually exclusive with blueGreen and rolling.

blueGreen
object

Blue-green rollout strategy configuration. Mutually exclusive with canary and rolling.

rolling
object

Rolling rollout strategy configuration. Mutually exclusive with canary and blueGreen.

metrics
object[]

Optional metric gates evaluated after each step's soak. Canary only; rejected on rolling and blue-green rollouts.

Metric gate evaluated during a rollout.

finalSourceReplicas
integer

Optional final replica count for the source deployment. Defaults to 0, which drains and stops the source.

finalTargetReplicas
integer

Optional target replica floor at completion. For rolling, the ladder climbs to this count one replica per rung. 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.

maxSurge
integer

Optional maximum target replicas one canary step may add. No canary step raises the target required replica count by more than this over the previous step (the target's current count before the first). Canary steps are admitted only when every raise fits. A rejection names the step, the counts, and the smallest maxSurge that admits the plan. Autoscaler growth on either deployment is not counted against the bound. Must be between 1 and 1000 when set. When unset, no step-raise bound applies. Available on the canary strategy only for now; a rolling or blue-green rollout that sets it is rejected at create and preview.

Required range: 1 <= x <= 1000
maxUnavailable
integer

Count of source replicas that may be missing or retired ahead of their replacements at any one time. Defaults to 0, so the rollout waits for capacity and refuses a degraded source. Spent three ways. A source already degraded at create (ready below desired by at most this many) is admitted. The engine retires source replicas ahead of a target raise to stay under maxSurge. When the target cannot be placed, it retires source replicas to make room, and only when both legs use the same GPU type; a target that cannot be placed on the source's cluster gains nothing from the retire, and the rollout then pauses naming it. It is a concurrent bound measured against the source's routed-share need, which drops after every traffic shift, so a full cluster is walked rung by rung. The last source replica is never retired before traffic moves, except at the final 100% rung, where the allowance may stop the source before the target's last replicas are ready. A 1-replica source with maxUnavailable 1 on a full cluster serves nothing while the replacement starts.

Required range: 0 <= x <= 1000

Response

OK

Completed create-form state — the caller's spec with defaulted values filled in, the steps the rollout is expected to walk, and the capacity context the defaults were computed from. Display only.

spec
object
required

The caller's spec with defaulted values filled in for display. canary.steps is echoed exactly as sent; the suggested ladder is returned in estimatedEffectiveSteps instead.

sourceReplicas
integer
required

Source deployment replica count the defaults were computed from. Zero is a real value.

targetReplicas
integer
required

Target deployment replica count the defaults were computed from. Zero is a real value.

targetMinReplicas
integer
required

Target deployment autoscaling minimum replica count. Zero is a real value.

targetMaxReplicas
integer
required

Target deployment autoscaling maximum replica count. Zero is a real value.

warnings
object[]
required

Findings to surface next to the form when a later gate will refuse the spec or a standing guarantee is lost. An empty list means the shown values are safe to submit as-is; render message for unrecognized codes.

estimatedEffectiveSteps
object[]

Steps the rollout is expected to walk when the caller leaves steps unset. Display only. Empty when the caller supplied steps or no ladder applies.

frozenPair
boolean

True when both deployments stand in the endpoint traffic split, so the rollout resumes from the current split rather than from zero. See warnings for standing split shapes that StartRollout will still reject.

estimatedSeedPercent
integer

Percentage of the pair's traffic currently reaching the target, the floor the suggested steps start above. Unset when not a frozen pair or unknown; 0 is a real measurement.

landingMinReplicas
integer

Expected autoscaling minimum replicas for the completed target; unset while the final target replicas cannot be resolved.

landingMaxReplicas
integer

Expected autoscaling maximum replicas for the completed target; unset while the final target replicas cannot be resolved.