Update an experiment

Partial update. allocation_pct, groups, salt, universe, params are immutable while running — returns 409 if you try. Stop the experiment first.

Partial update. allocation_pct, groups, salt, universe, params are immutable while running — returns 409 if you try. Stop the experiment first.

Editing groups while in draft is fine; weights must still sum to 10000.

Use cases

Update metadata — description, tag, targeting_gate editable any time.
Ramp before launch — set allocation_pct while still in draft.
Tighten significance — significance_threshold (Pro+).
Rewire groups — replace groups wholesale while in draft; immutable once running.

Authorization

bearerSdkKey

AuthorizationBearer <token>

Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".

In: header

Path Parameters

id*string

Stable opaque experiment id (exp_…) or the experiment's name.

Length1 <= length <= 128

Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Stable experiment key. Single segment or folder.name (a-z, 0-9, _/-; max 128 chars). Used by SDKs as Shipeasy.getExperiment(user, '<name>'). Immutable after create.

Match^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$

Lengthlength <= 128

description?|null

hypothesis?|null

tag?|null

owner_email?|null

audience?|null

bucket_by?|null

folder?|

Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).

targeting_gate?string|null

holdout_gate?|

Per-experiment holdout gate — the name of a holdout-type flag, or null to clear. A caller the flag passes is held out.

allocation_pct?integer

Basis-points allocation (0–10000). Use allocation_percent (0–100) for percent. Immutable while the experiment is running.

Range0 <= value <= 10000

reserved_headroom?integer

Basis points of the split kept empty for appended variants. Group weights must sum to 10000 − reserved_headroom. May be shrunk (never grown into existing weights) while running when appending a variant.

Range0 <= value <= 10000

allocation_percent?number

Allocation as a percentage (0–100). Friendlier alias for allocation_pct; converted to basis points server-side. Wins over allocation_pct if both are supplied. Immutable while running.

Range0 <= value <= 100

salt?string

Hash salt. Immutable while running.

Length1 <= length <= 64

universe?string

New universe name. Immutable while running. Returns 422 if the universe doesn't exist.

params?

Deprecated — the universe owns the config schema (param_schema). Retained for back-compat. Map of param-name → scalar type.

groups?array<>

Replacement groups. Weights must sum to 10000 − reserved_headroom. Existing weights/values are immutable while running; a new variant may be appended into the reserved tail.

Items2 <= items

significance_threshold?number

Range0.0001 <= value <= 0.5

min_runtime_days?integer

Range0 <= value <= 365

min_sample_size?integer

Range1 <= value <= 9007199254740991

sequential_testing?boolean

goal_metric?

Replaces the goal metric — DSL query or event (+aggregation/value) the server compiles (event auto-upserted).

guardrail_metrics?array<>

Replaces the guardrail set wholesale (event auto-upserted per entry).

Itemsitems <= 10

Response Body

`application/json`

curl -X PATCH "https://shipeasy.ai/api/admin/experiments/string" \  -H "Content-Type: application/json" \  -d '{    "allocation_pct": 5000  }'

{
  "id": "exp_01j7wb12c3d4e5f6g7h8j9k0l1"
}

{
  "error": "Malformed request (bad JSON, missing project scope).",
  "code": "BAD_REQUEST"
}

{
  "error": "Missing or invalid admin SDK key.",
  "code": "UNAUTHORIZED"
}

{
  "error": "Key is valid but not allowed to act on this project.",
  "code": "FORBIDDEN"
}

{
  "error": "The resource does not exist or is not visible to the caller.",
  "code": "NOT_FOUND"
}

{
  "error": "A resource with this name already exists in the project.",
  "code": "ALREADY_EXISTS"
}

{
  "error": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?

✎ Edit this page

Update an experiment

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

Not an admin of this project

Feature gated behind a higher plan

Duplicate name

Still referenced by another resource

Illegal lifecycle transition

Edited an immutable field while running

Schema validation failed

Referenced entity missing

Group weights must sum to 10000

Event still pending review

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`