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

# Public Config Endpoint

> Fetch feature flag configs for client applications

# Public Config Endpoint

The `/public-config` endpoint returns filtered flag configs for client-side applications (browsers, mobile apps).

## Endpoint

```
GET /api/v1/public-config
```

## Authentication

Use a **public client key** (`pub_*`) in the Authorization header:

```bash theme={null}
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_prod_..."
```

<Warning>
  Only use public keys (`pub_*`) in client-side code. Never use server keys (`sdk_*`) in browsers or mobile apps.
</Warning>

## Response

### Success (200 OK)

```json theme={null}
{
  "appId": "app_abc123",
  "env": "production",
  "version": 42,
  "doc": {
    "flags": {
      "dark-mode": {
        "type": "bool",
        "value": true
      },
      "api-url": {
        "type": "string",
        "value": "https://api.example.com"
      },
      "max-items": {
        "type": "number",
        "value": 100
      },
      "theme-config": {
        "type": "json",
        "value": {
          "primaryColor": "#3B82F6",
          "borderRadius": 8
        }
      }
    },
    "overrides": {},
    "rules": {}
  },
  "ttlSeconds": 60
}
```

### Not Modified (304)

If you provide an `If-None-Match` header with the current ETag, and the config hasn't changed:

```bash theme={null}
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_..." \
  -H "If-None-Match: \"v42\""

# Returns 304 Not Modified with no body
```

### Unauthorized (401)

Invalid or missing key:

```json theme={null}
{
  "error": "Invalid or unauthorized client key"
}
```

### Rate Limited (429)

Monthly quota exceeded:

```json theme={null}
{
  "error": "Monthly quota exceeded"
}
```

## Response Fields

| Field           | Type   | Description             |
| --------------- | ------ | ----------------------- |
| `appId`         | string | App identifier          |
| `env`           | string | Environment name        |
| `version`       | number | Config version number   |
| `doc.flags`     | object | Flag key-value pairs    |
| `doc.overrides` | object | Reserved for future use |
| `doc.rules`     | object | Reserved for future use |
| `ttlSeconds`    | number | Recommended cache TTL   |

## Flag Types

Each flag has a `type` and `value`:

| Type     | Example Value          |
| -------- | ---------------------- |
| `bool`   | `true` or `false`      |
| `string` | `"light"` or `"dark"`  |
| `number` | `100` or `3.14`        |
| `json`   | `{"color": "#3B82F6"}` |

## ETag Caching

The response includes an `ETag` header based on the version:

```
ETag: "v42"
```

On subsequent requests, send the ETag in `If-None-Match`:

```bash theme={null}
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_..." \
  -H "If-None-Match: \"v42\""
```

If the config hasn't changed, you'll get a `304 Not Modified` response with no body, saving bandwidth.

## Examples

### Fetch Config (JavaScript)

```javascript theme={null}
const response = await fetch('https://superflag.sh/api/v1/public-config', {
  headers: {
    'Authorization': `Bearer ${clientKey}`
  }
})

const data = await response.json()
console.log(data.doc.flags)
```

### With ETag (JavaScript)

```javascript theme={null}
let etag = localStorage.getItem('superflag-etag')

const response = await fetch('https://superflag.sh/api/v1/public-config', {
  headers: {
    'Authorization': `Bearer ${clientKey}`,
    ...(etag && { 'If-None-Match': etag })
  }
})

if (response.status === 304) {
  // Use cached config
  const cached = JSON.parse(localStorage.getItem('superflag-config'))
  return cached
}

const data = await response.json()

// Save new config and ETag
localStorage.setItem('superflag-config', JSON.stringify(data))
localStorage.setItem('superflag-etag', response.headers.get('ETag'))

return data
```

### Curl

```bash theme={null}
# Basic request
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_prod_..."

# With ETag
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_prod_..." \
  -H "If-None-Match: \"v42\"" \
  -v  # Show 304 status
```

## SDK Usage

The official SDKs handle this endpoint automatically with ETag caching:

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    import { SuperflagProvider, useFlag } from '@superflag-sh/react'

    function App() {
      return (
        <SuperflagProvider clientKey="pub_prod_...">
          <MyComponent />
        </SuperflagProvider>
      )
    }

    function MyComponent() {
      const darkMode = useFlag('dark-mode', false)
      return <div>{darkMode ? 'Dark' : 'Light'}</div>
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { SuperflagProvider, useFlag } from '@superflag-sh/react-native'
    import { Text } from 'react-native'

    export default function App() {
      return (
        <SuperflagProvider clientKey="pub_prod_...">
          <MyScreen />
        </SuperflagProvider>
      )
    }

    function MyScreen() {
      const darkMode = useFlag('dark-mode', false)
      return <Text>{darkMode ? 'Dark' : 'Light'}</Text>
    }
    ```
  </Tab>
</Tabs>

## Error Handling

Always handle potential errors:

```javascript theme={null}
try {
  const response = await fetch('https://superflag.sh/api/v1/public-config', {
    headers: { 'Authorization': `Bearer ${clientKey}` }
  })

  if (response.status === 401) {
    console.error('Invalid client key')
    return fallbackConfig
  }

  if (response.status === 429) {
    console.warn('Rate limited - using cached config')
    return cachedConfig
  }

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`)
  }

  return await response.json()
} catch (error) {
  console.error('Failed to fetch config:', error)
  return fallbackConfig
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Overview" icon="book" href="/api-reference/overview">
    Authentication and general API info
  </Card>

  <Card title="Management API" icon="wrench" href="/api-reference/management">
    Manage flags programmatically
  </Card>
</CardGroup>