> ## 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. # Update a shadow experiment > Updates a shadow experiment's description or source sampling strategy. `updateMask` is required; source changes also require the current `etag` in the request body. ## OpenAPI ````yaml PATCH /projects/{projectId}/endpoints/{endpointId}/shadowExperiments/{id} 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}/shadowExperiments/{id}: patch: tags: - ShadowExperimentService summary: Update a shadow experiment description: >- Updates a shadow experiment's description or source sampling strategy. `updateMask` is required; source changes also require the current `etag` in the request body. operationId: ShadowExperimentService_UpdateShadowExperiment 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 - name: id in: path required: true schema: description: Shadow experiment identifier. type: string - name: updateMask in: query required: true schema: type: string description: Required fields to update, such as description or source. requestBody: content: application/json: schema: $ref: '#/components/schemas/DE.UpdateShadowExperimentRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DE.ShadowExperiment' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorData' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/ErrorData' servers: - url: https://api.together.ai/v2 components: schemas: DE.UpdateShadowExperimentRequest: type: object description: >- Mutable description and source sampling strategy for a shadow experiment. properties: description: type: string description: Updated free-form description. source: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentSource' description: >- Updated endpoint sampling configuration. Source updates require etag in the request body. etag: type: string description: Opaque version tag from a prior read for optimistic concurrency. DE.ShadowExperiment: type: object description: >- Experiment that mirrors sampled endpoint requests to target deployments without changing client responses. required: - id - projectId - endpointId - name - source - targets - createdAt - createdBy - updatedAt - etag - state properties: id: type: string description: Output only. Unique shadow experiment identifier. readOnly: true projectId: type: string description: Output only. Project that owns the parent endpoint. readOnly: true endpointId: type: string description: Output only. Endpoint whose traffic this experiment samples. readOnly: true name: type: string description: >- Human-readable shadow experiment name, unique within the endpoint. At most 256 characters. description: type: string description: User defined description. source: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentSourceResponse' description: Endpoint source and sampling configuration for mirrored requests. targets: type: array items: $ref: '#/components/schemas/DE.ShadowExperimentTarget' description: Target deployments that receive mirrored traffic. createdBy: type: string description: Identifier of the principal that created the experiment. readOnly: true createdAt: type: string description: Timestamp when the experiment was created. format: date-time readOnly: true updatedAt: type: string description: Timestamp when the experiment was last updated. format: date-time readOnly: true etag: type: string description: >- Opaque version tag for optimistic concurrency control. Returned on read; set it on update or delete requests for consistent read-modify-write. state: type: string enum: - SHADOW_EXPERIMENT_STATE_ACTIVE - SHADOW_EXPERIMENT_STATE_INACTIVE description: >- Derived serving state, active when the experiment has at least one target. 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.ShadowExperimentSource: type: object description: >- Traffic source for a shadow experiment. The public API supports endpoint sources only. required: - endpoint properties: endpoint: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentEndpointSource' description: Endpoint-level source that samples traffic at the API gateway. DE.ShadowExperimentSourceResponse: type: object description: Endpoint traffic source returned for a shadow experiment. required: - endpoint properties: endpoint: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentEndpointSourceResponse' description: Endpoint-level source that samples traffic at the API gateway. DE.ShadowExperimentTarget: type: object description: Deployment that receives mirrored traffic for a shadow experiment. required: - id - experimentId - name - targetDeploymentId - createdAt - updatedAt - etag properties: id: type: string description: Output only. Unique shadow experiment target identifier. readOnly: true experimentId: type: string description: Output only. Shadow experiment this target belongs to. readOnly: true name: type: string description: >- Human-readable target name, unique within the shadow experiment. At most 256 characters. targetDeploymentId: type: string description: >- Deployment under the parent endpoint that receives mirrored traffic. Shadow targets should be excluded from the endpoint's live traffic split. description: type: string description: Optional free-form target description. createdAt: type: string description: Output only. Timestamp when the target was created. format: date-time readOnly: true updatedAt: type: string description: Output only. Timestamp when the target was last updated. format: date-time readOnly: true etag: type: string description: >- Opaque version tag for optimistic concurrency control. Returned on read; set it on update or delete requests for consistent read-modify-write. DE.ShadowExperimentEndpointSource: type: object description: Endpoint-level source that samples endpoint traffic at the API gateway. required: - sampling properties: sampling: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentSampling' description: Sampling strategy applied to endpoint traffic. DE.ShadowExperimentEndpointSourceResponse: type: object description: Endpoint-level source returned for a shadow experiment. required: - sampling properties: sampling: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentSamplingResponse' description: Resolved sampling strategy applied to endpoint traffic. DE.ShadowExperimentSampling: description: >- Sampling strategy for endpoint-level shadow traffic. Exactly one strategy must be set. oneOf: - type: object x-stainless-variantName: Uniform required: - uniform properties: uniform: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentUniformSampling' description: Fixed random request sampling. - type: object x-stainless-variantName: KeyBased required: - keyBased properties: keyBased: allOf: - $ref: '#/components/schemas/DE.ShadowExperimentKeyBasedSampling' description: Fixed sampling by a sticky request key. - type: object x-stainless-variantName: AdaptiveUniform required: - adaptiveUniform properties: adaptiveUniform: allOf: - $ref: >- #/components/schemas/DE.ShadowExperimentAdaptiveUniformSampling description: Adaptive random sampling toward a target QPS. - type: object x-stainless-variantName: AdaptiveKeyBased required: - adaptiveKeyBased properties: adaptiveKeyBased: allOf: - $ref: >- #/components/schemas/DE.ShadowExperimentAdaptiveKeyBasedSampling description: Adaptive sticky-key sampling toward a target QPS. DE.ShadowExperimentSamplingResponse: description: Sampling strategy returned for endpoint-level shadow traffic. oneOf: - type: object x-stainless-variantName: Uniform required: - uniform properties: uniform: allOf: - $ref: >- #/components/schemas/DE.ShadowExperimentUniformSamplingResponse description: Fixed random request sampling. - type: object x-stainless-variantName: KeyBased required: - keyBased properties: keyBased: allOf: - $ref: >- #/components/schemas/DE.ShadowExperimentKeyBasedSamplingResponse description: Fixed sampling by a sticky request key. - type: object x-stainless-variantName: AdaptiveUniform required: - adaptiveUniform properties: adaptiveUniform: allOf: - $ref: >- #/components/schemas/DE.ShadowExperimentAdaptiveUniformSamplingResponse description: Adaptive random sampling toward a target QPS. - type: object x-stainless-variantName: AdaptiveKeyBased required: - adaptiveKeyBased properties: adaptiveKeyBased: allOf: - $ref: >- #/components/schemas/DE.ShadowExperimentAdaptiveKeyBasedSamplingResponse description: Adaptive sticky-key sampling toward a target QPS. DE.ShadowExperimentUniformSampling: type: object description: Fixed-rate random sampling of endpoint requests. required: - rate properties: rate: type: number description: Required fraction of requests to sample, from 0.0 to 1.0. DE.ShadowExperimentKeyBasedSampling: type: object description: Fixed-rate sampling of distinct key values with sticky decisions. required: - rate - key properties: rate: type: number description: Required fraction of distinct key values to sample, from 0.0 to 1.0. key: type: string description: Required request-body field used as the sticky sampling key. DE.ShadowExperimentAdaptiveUniformSampling: type: object description: Adaptive random sampling that throttles toward a target QPS. required: - targetQps properties: targetQps: type: number description: Required per-gateway-replica target QPS for adaptive sampling. window: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: >- Optional sliding window for QPS observation. Defaults to 60s and must not be negative. DE.ShadowExperimentAdaptiveKeyBasedSampling: type: object description: Adaptive sticky-key sampling that throttles toward a target QPS. required: - targetQps - key properties: targetQps: type: number description: Required per-gateway-replica target QPS for adaptive sampling. key: type: string description: Required request-body field used as the sticky sampling key. window: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: >- Optional sliding window for QPS observation. Defaults to 60s and must not be negative. DE.ShadowExperimentUniformSamplingResponse: type: object description: >- Fixed-rate random sampling returned by the API. A zero rate may be omitted by JSON serialization. properties: rate: type: number description: Fraction of requests sampled, from 0.0 to 1.0. DE.ShadowExperimentKeyBasedSamplingResponse: type: object description: >- Fixed-rate sticky-key sampling returned by the API. A zero rate may be omitted by JSON serialization. required: - key properties: rate: type: number description: Fraction of distinct key values sampled, from 0.0 to 1.0. key: type: string description: Request-body field used as the sticky sampling key. DE.ShadowExperimentAdaptiveUniformSamplingResponse: type: object description: Adaptive random sampling returned by the API. required: - targetQps properties: targetQps: type: number description: Per-gateway-replica target QPS. window: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: Sliding window for QPS observation when explicitly configured. DE.ShadowExperimentAdaptiveKeyBasedSamplingResponse: type: object description: Adaptive sticky-key sampling returned by the API. required: - targetQps - key properties: targetQps: type: number description: Per-gateway-replica target QPS. key: type: string description: Request-body field used as the sticky sampling key. window: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: Sliding window for QPS observation when explicitly configured. securitySchemes: bearerAuth: type: http scheme: bearer x-bearer-format: bearer x-default: default ````