> ## 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.

# Get Flag Configuration

> Fetch the flag configuration payload polled by game servers

The payload your servers poll. Returns every flag your organization holds — archived ones excluded — as a flat list a game server can parse.

This endpoint is served from an edge cache, so a poll never reaches the database. Send the `ETag` you already hold as `If-None-Match` and an unchanged configuration is answered with a `304` and no body.

<Note>
  This is the only flags endpoint a game server needs. It requires `FLAGS_READ`
  only, so the API key you ship to a server never has to be able to change a
  flag.
</Note>

## Authorization

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

## Required Permission

`FLAGS_READ`

## Headers

<ParamField header="If-None-Match" type="string">
  The `ETag` from your previous response. When it matches the current
  configuration the response is `304 Not Modified` with an empty body. Both weak
  (`W/"a1b2c3d4e5f6a7b8"`) and bare forms are accepted.
</ParamField>

## Response Headers

<ResponseField name="ETag" type="string">
  Weak validator for the current configuration, e.g. `W/"a1b2c3d4e5f6a7b8"`. It
  is a hash of the flags the payload contains, so an unchanged set of flags
  always produces the same value.
</ResponseField>

<ResponseField name="Cache-Control" type="string">
  Always `no-cache, must-revalidate`. Servers must revalidate on every poll so a
  flag change reaches them on the next request rather than whenever an
  intermediary decides its copy expired.
</ResponseField>

## Response

<ResponseField name="etag" type="string">
  The same validator as the `ETag` header.
</ResponseField>

<ResponseField name="generatedAt" type="string">
  ISO 8601 timestamp of when this payload was built.
</ResponseField>

<ResponseField name="pollIntervalSeconds" type="number">
  Seconds the API suggests waiting before polling again. Currently `20`. This is
  advisory — the SDKs use it to warn when you are polling faster than it.
</ResponseField>

<ResponseField name="flags" type="FlagConfigEntry[]">
  Every non-archived flag, ordered by key.
</ResponseField>

<Expandable title="FlagConfigEntry properties">
  <ResponseField name="key" type="string">
    The flag's key.
  </ResponseField>

  <ResponseField name="type" type="string">
    `boolean`, `string`, `number`, or `json`.
  </ResponseField>

  <ResponseField name="value" type="JsonValue">
    The flag's current value, matching its type.
  </ResponseField>

  <ResponseField name="runtime" type="string">
    `shared` or `server`. Every flag in this payload reaches your server —
    `runtime` says whether you may relay it to players. **Your server is what
    enforces this**; a `server` flag must never be forwarded to a client.
  </ResponseField>
</Expandable>

## Status Codes

| Status | Meaning                                        |
| ------ | ---------------------------------------------- |
| `200`  | The configuration, as JSON                     |
| `304`  | Your `If-None-Match` matched — nothing changed |
| `401`  | Invalid or missing API key                     |
| `403`  | The key lacks `FLAGS_READ`                     |
| `429`  | Rate limit exceeded                            |

## Rate Limit

This endpoint has its own allowance of **1200 requests per minute per API key**, separate from the general cloud limit. Authentication happens before rate limiting, so the count is per key rather than per IP — servers behind the same address do not compete.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.nonefivem.com/cloud/flags/config" \
    -H "Authorization: Bearer your-api-key"
  ```

  ```bash cURL (revalidate) theme={null}
  curl -X GET "https://api.nonefivem.com/cloud/flags/config" \
    -H "Authorization: Bearer your-api-key" \
    -H 'If-None-Match: W/"a1b2c3d4e5f6a7b8"'
  ```

  ```javascript JavaScript theme={null}
  let etag = null;

  async function pollFlags() {
    const response = await fetch(
      "https://api.nonefivem.com/cloud/flags/config",
      {
        headers: {
          Authorization: "Bearer your-api-key",
          ...(etag ? { "If-None-Match": etag } : {})
        }
      }
    );

    if (response.status === 304) return null; // nothing changed

    etag = response.headers.get("ETag");

    return response.json();
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "etag": "a1b2c3d4e5f6a7b8",
    "generatedAt": "2026-09-19T12:00:00.000Z",
    "pollIntervalSeconds": 20,
    "flags": [
      {
        "key": "economy",
        "type": "json",
        "value": { "payMultiplier": 1.5, "taxRate": 0.1 },
        "runtime": "shared"
      },
      {
        "key": "max-players",
        "type": "number",
        "value": 64,
        "runtime": "shared"
      },
      {
        "key": "new-hud",
        "type": "boolean",
        "value": true,
        "runtime": "shared"
      },
      {
        "key": "webhook-url",
        "type": "string",
        "value": "https://discord.com/api/webhooks/...",
        "runtime": "server"
      }
    ]
  }
  ```
</ResponseExample>