Create a universe

Creates a new universe. Only name is required — unit_type defaults to user_id and holdout_range defaults to null (no holdout).

Creates a new universe. Only name is required — unit_type defaults to user_id and holdout_range defaults to null (no holdout).

Returns 409 if name already exists in the project. Returns 403 if you supply holdout_range on a plan below Pro.

Use cases

Default universe — { "name": "primary_users" }. Per-user randomisation, no holdout.
Reserved holdout — supply holdout_range to carve out a measurement slice excluded from all experiments.
Account-level — unit_type: 'account_id' so multi-seat accounts see one consistent variant.

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

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 universe key. Single segment or folder.name. Lowercase letters, digits, _ or -; max 128 chars. Immutable after create.

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

Lengthlength <= 128

folder?|

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

description?|

Human-readable blurb shown in the universe picker/hovercard.

Defaultnull

unit_type?string

Unit of randomisation. Typically user_id. Use account_id to keep whole accounts in the same group across an experiment.

Default"user_id"

holdout_range?array<>|

Inclusive [lo, hi] bucket range (0–9999) reserved as the holdout — callers hashed into this slice are excluded from every experiment in the universe. null disables the holdout. Pro plan or higher required.

Defaultnull

recommended_headroom?integer

Basis points of reserved headroom seeded into each new experiment created in this universe (0 = none). Lets variants be appended into a running experiment without reshuffling.

Default0

Range0 <= value <= 10000

param_schema?array<>|

The universe-owned config schema — an ordered { name, type, default }[]. Experiments may only override values per variant, never add fields. null starts an empty schema.

Defaultnull

Response Body

`application/json`

curl -X POST "https://shipeasy.ai/api/admin/universes" \  -H "Content-Type: application/json" \  -d '{    "name": "primary_users"  }'

{
  "id": "uni_01j7w8a1b2c3d4e5f6g7h8i9j0",
  "name": "primary_users"
}

{
  "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

Create a universe

Authorization

Header Parameters

Request Body

Response Body

201application/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`