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

# API Overview

> HTTP API reference for Superflag

# API Reference

Superflag provides a REST API for fetching configs and managing flags programmatically.

## Base URL

```
https://superflag.sh/api/v1
```

## Authentication

Superflag uses different key types for different use cases:

| Key Type   | Prefix   | Use Case                      | Permissions            |
| ---------- | -------- | ----------------------------- | ---------------------- |
| **Public** | `pub_`   | Client SDKs (browser, mobile) | Read filtered config   |
| **SDK**    | `sdk_`   | Server SDKs                   | Read full config       |
| **CLI**    | `cli_`   | CLI tool                      | Full management access |
| **Admin**  | `admin_` | App management API            | App-level admin        |

### Authorization Header

All API requests use Bearer token authentication:

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

## Endpoints

### Client Endpoints

For fetching configs in your application:

| Endpoint         | Method | Auth    | Description                     |
| ---------------- | ------ | ------- | ------------------------------- |
| `/public-config` | GET    | `pub_*` | Get filtered config for clients |
| `/config`        | GET    | `sdk_*` | Get full config for servers     |

### Management Endpoints

For managing flags, apps, and keys:

| Endpoint | Method                   | Auth    | Description          |
| -------- | ------------------------ | ------- | -------------------- |
| `/apps`  | GET, POST                | `cli_*` | List and create apps |
| `/flags` | GET, POST, PATCH, DELETE | `cli_*` | Manage flags         |
| `/keys`  | GET, POST, PATCH         | `cli_*` | Manage API keys      |

## Response Format

All responses return JSON with this structure:

### Success Response

```json theme={null}
{
  "data": { ... }
}
```

### Error Response

```json theme={null}
{
  "error": "Error message"
}
```

## Status Codes

| Code  | Meaning                                 |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `201` | Created                                 |
| `304` | Not Modified (ETag match)               |
| `400` | Bad Request                             |
| `401` | Unauthorized (invalid or missing key)   |
| `403` | Forbidden (key doesn't have permission) |
| `404` | Not Found                               |
| `429` | Rate Limited (quota exceeded)           |
| `500` | Server Error                            |

## Rate Limiting

API requests are metered based on your plan:

* **Free**: 25,000 requests/month/environment
* **Pro**: 100,000 requests/month/environment
* **Enterprise**: Custom limits

When you exceed your quota, you'll receive a `429` status code. The SDKs will continue serving cached configs.

## ETag Caching

The `/public-config` and `/config` endpoints support ETag-based caching to minimize bandwidth:

**First Request:**

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

# Response includes ETag header
ETag: "v123"
```

**Subsequent Request:**

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

# If unchanged, returns 304 Not Modified (no body, minimal bandwidth)
# If changed, returns 200 with new config and updated ETag
```

This is how the SDKs achieve 90%+ bandwidth reduction.

## CORS

The API supports CORS for browser-based requests:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type, If-None-Match
```

## Versioning

The API is versioned via URL path (`/api/v1`). Breaking changes will increment the version number (`/api/v2`).

Current version: **v1**

## SDKs

Official SDKs handle authentication, caching, and error handling for you:

* **React**: `@superflag-sh/react`
* **React Native**: `@superflag-sh/react-native`
* **CLI**: `@superflag-sh/cli`

## Next Steps

<CardGroup cols={2}>
  <Card title="Public Config Endpoint" icon="globe" href="/api-reference/public-config">
    Fetch configs for client apps
  </Card>

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