Feature Flags

Creates a feature flag in the resolved project.

Requires at least Member. Type is passed through verbatim to Type (a bare string) — an invalid value surfaces as the handler's own validation failure. Re-fetches via GetFeatureFlagQuery so the response reflects exactly what was persisted (e.g. server-assigned variation ids). A flag past the plan's per-project cap on active flags is a 403 plan_limit_reached.

post/api/v1/orgs/{org}/projects/{project}/flags

Request

  • Base URL: https://api.featureflip.io
  • URL: https://api.featureflip.io/api/v1/orgs/{org}/projects/{project}/flags
  • Auth: API key in header Authorization

Path parameters

orgstring required
projectstring required

Request body

keystring nullable required
namestring nullable required
type'Boolean' | 'String' | 'Number' | 'Json' nullable required

Allowed values: Boolean, String, Number, Json.

descriptionstring nullable
tagsstring[] nullable
clientSideVisibleboolean
expiresAtUtcstring date-time nullable
ownerEmailstring nullable
isPermanentboolean

Example request

{
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "type": "Boolean",
  "description": "Gates the redesigned checkout experience.",
  "tags": [
    "checkout",
    "q3-launch"
  ],
  "initialVariations": [
    {
      "key": "true",
      "name": "Enabled",
      "value": "true",
      "description": "Serve the new checkout."
    },
    {
      "key": "false",
      "name": "Disabled",
      "value": "false",
      "description": "Serve the legacy checkout."
    }
  ],
  "clientSideVisible": false
}

Response

Created

idstring uuid required
keystring nullable required
namestring nullable required
descriptionstring nullable
type'Boolean' | 'String' | 'Number' | 'Json' nullable required

Allowed values: Boolean, String, Number, Json.

isArchivedboolean required
clientSideVisibleboolean required
tagsstring[] nullable required
createdAtstring date-time required
updatedAtstring date-time required
expiresAtUtcstring date-time nullable
removalPrUrlstring nullable
isPermanentboolean required
effectiveExpiresAtUtcstring date-time nullable
expirySourcestring nullable
_actionsobject

Capability hints: which operations the authenticated caller may perform on this resource, each with allowed + optional reason. Computed from the caller's role and the resource's state. Injected at runtime; safe to ignore. Present only on top-level resource responses — nested occurrences (e.g. a rule inside a targeting-config response) do not carry it.

Example response

{
  "id": "0197b6a0-5f2a-7c3e-9b4d-1e2f3a4b5c6d",
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "description": "Gates the redesigned checkout experience.",
  "type": "Boolean",
  "isArchived": false,
  "clientSideVisible": false,
  "tags": [
    "checkout",
    "q3-launch"
  ],
  "variations": [
    {
      "id": "0197b6a0-6a1b-7d4f-8c2e-2f3a4b5c6d7e",
      "key": "true",
      "name": "Enabled",
      "value": "true",
      "description": "Serve the new checkout."
    },
    {
      "id": "0197b6a0-6a1b-7d4f-8c2e-3a4b5c6d7e8f",
      "key": "false",
      "name": "Disabled",
      "value": "false",
      "description": "Serve the legacy checkout."
    }
  ],
  "createdAt": "2026-06-01T12:00:00Z",
  "updatedAt": "2026-06-15T08:30:00Z",
  "isPermanent": false
}

Changes

No recorded changes to this operation across all 1 revision of this API.