Create a feature gate

Creates a new gate. Default enabled: true at the supplied rollout_pct (0 = fully dark).

Creates a new gate. Default enabled: true at the supplied rollout_pct (0 = fully dark).

Only name is required. Request fields use snake_case (owner_email); the GET response returns camelCase (ownerEmail, groupName).

Returns 409 if name already exists in the project (case-sensitive).

Use cases

Dark create + ramp later — { "name": "checkout_v2" } at 0% rollout. Ramp via PATCH after deploy validation.
Targeted rollout — supply rules to gate the caller (e.g. only plan = pro users) plus a rollout_pct to bucket within that audience.
Gatekeeper stack — supply stack instead of rules/rollout_pct for internal ∪ beta ∪ public fall-through. Stack entries evaluated top-to-bottom; first match wins.
Dashboard metadata — populate title, description, folder, group, owner_email so the admin UI is self-documenting from day one.
Disabled on create — pre-provision with enabled: false for a future launch; flip on with POST /{id}/enable at go-live.

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 gate key used by SDKs (Shipeasy.checkGate(user, '<name>')). Single segment or folder.name. Lowercase letters, digits, _ or -; max 128 chars. Immutable after create — rename = delete + recreate.

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

Lengthlength <= 128

type?string

Gate kind. targeting (default) is a normal flag with the full builder. holdout is a restricted flag — only a public rollout % and a whitelist are allowed; attribute rules and a gatekeeper stack are rejected. Used as an experiment's holdout_gate.

Default"targeting"

Value in"targeting" | "holdout"

enabled?boolean

Master switch. Defaults to true. Set false to create the gate disabled (evaluates to false regardless of rules/rollout); flip on via POST /{id}/enable or PATCH.

Defaulttrue

rollout_pct?integer

Initial rollout in basis points (0–10000 = 0%–100%) — 100 here means 1%, not 100%. Use rollout_percent (0–100) below if you'd rather think in percent. Use 0 to create the gate dark and ramp via PATCH after deploy validation.

Default0

Range0 <= value <= 10000

rollout_percent?number

Initial rollout as a percentage (0–100, fractional ok). Friendlier alias for rollout_pct; converted internally to basis points (e.g. 100 here = 10000 bp = 100%). If both rollout_pct and rollout_percent are set, rollout_percent wins.

Range0 <= value <= 100

rules?array<>

Targeting predicates. AND-combined. If non-empty, the gate returns true only for callers that satisfy every rule and fall under rollout_pct.

Default[]

salt?string

Hash salt for percentage bucketing. Auto-generated if omitted. Provide explicitly to keep a gate's buckets stable across delete/recreate. Immutable after create — there is no PATCH for salt because changing it would re-bucket every caller.

Length1 <= length <= 64

stack?array<|>|

Optional gatekeeper stack. When provided, takes precedence over rules + rollout_pct at evaluation time. Omit (or pass null) for a flat gate.

title?string

Human-readable title shown in the dashboard. Free-form, no key format constraint.

Lengthlength <= 140

description?string

Long-form description / runbook. Markdown is rendered in the dashboard.

Lengthlength <= 2000

folder?|

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

group?string

Group label for dashboard organisation (e.g. team or product area).

Lengthlength <= 64

owner_email?string

Owner contact. Displayed verbatim; not used for auth.

Lengthlength <= 190

Response Body

`application/json`

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

{
  "id": "gat_01j7w7m9q4hxbf6npe6s9zr3vc",
  "name": "checkout_v2"
}

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

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`