> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonefivem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Feature Flag

> Create a feature flag with its initial typed value

Creates a flag and publishes it to your servers immediately.

## Authorization

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <your-api-key>`
</ParamField>

## Required Permission

`FLAGS_WRITE`

## Body Parameters

<ParamField body="key" type="string" required>
  The immutable slug your code reads the flag by, 1–64 characters. Must match
  `^[a-z0-9][a-z0-9_-]*$` — it starts with a lowercase letter or number and
  contains only lowercase letters, numbers, hyphens and underscores.
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable name, 1–100 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional description, up to 500 characters.
</ParamField>

<ParamField body="type" type="string" required>
  The kind of value this flag holds: `boolean`, `string`, `number`, or `json`.
</ParamField>

<ParamField body="value" type="JsonValue" required>
  The flag's initial value. It is validated against `type`: a `number` flag must
  hold a finite number, a `boolean` flag `true` or `false`, and so on. Serialized
  size must not exceed 4 KB, and JSON values may not nest deeper than 4 levels.
</ParamField>

<ParamField body="runtime" type="string" default="shared">
  `shared` (your server and players' clients) or `server` (your server only).
</ParamField>

<Warning>
  `runtime` defaults to `shared`, which means players' clients can read the
  value. Anything holding a secret must be created with `"runtime": "server"`.
</Warning>

## Response

Returns the created flag — the same shape as a single entry in
[`GET /flags`](/cloud/api-reference/flags/list) — with status `201`.

## Status Codes

| Status | Meaning                                                            |
| ------ | ------------------------------------------------------------------ |
| `201`  | The flag was created                                               |
| `400`  | Validation failed — bad key, or a value that does not match `type` |
| `401`  | Invalid or missing API key                                         |
| `403`  | The key lacks `FLAGS_WRITE`                                        |
| `409`  | The key is already taken, or you are at your flag allowance        |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.nonefivem.com/cloud/flags" \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "new-hud",
      "name": "New HUD",
      "description": "Rolls out the redesigned heads-up display",
      "type": "boolean",
      "value": true,
      "runtime": "shared"
    }'
  ```

  ```bash cURL (server-only) theme={null}
  curl -X POST "https://api.nonefivem.com/cloud/flags" \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "webhook-url",
      "name": "Alert webhook",
      "type": "string",
      "value": "https://discord.com/api/webhooks/...",
      "runtime": "server"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.nonefivem.com/cloud/flags", {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      key: "economy",
      name: "Economy tuning",
      type: "json",
      value: { payMultiplier: 1.5, taxRate: 0.1 }
    })
  });
  const flag = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "new-hud",
    "name": "New HUD",
    "description": "Rolls out the redesigned heads-up display",
    "type": "boolean",
    "value": true,
    "runtime": "shared",
    "archived": false,
    "locked": false,
    "createdAt": "2026-09-19T12:00:00.000Z",
    "updatedAt": "2026-09-19T12:00:00.000Z"
  }
  ```

  ```json 409 At allowance theme={null}
  {
    "message": "Free organizations are limited to 5 feature flags. Subscribe to raise the limit."
  }
  ```

  ```json 409 Key taken theme={null}
  {
    "message": "A feature flag with key \"new-hud\" already exists"
  }
  ```
</ResponseExample>