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

# Resolve Feature Flags with the SDK API

> Use a project-scoped API key to fetch all resolved flag values for a specific record in one request. Returns each flag's enabled state, rollout percentage, and source.

The SDK endpoint lets your application resolve all feature flag values for a specific record with a single HTTP request. Instead of checking flags one by one, you fetch the complete flag state for a record — an organization, a user, or any entity you've registered — and branch on the results in your code. This endpoint is authenticated with a **project-scoped API key**, not a session token, making it safe to call from server-side application code.

<Warning>
  Always call this endpoint from your server. API keys are project-scoped credentials — exposing them in client-side JavaScript or mobile app bundles gives anyone who finds the key access to your flag data. Store the key in an environment variable and proxy requests through your backend if needed.
</Warning>

## Authentication

Generate an API key from **Feature Flags → API Keys** in the dashboard. Each key is scoped to a single project and must be passed as a bearer token on every request.

For more detail on creating and rotating keys, see [API Keys](/concepts/api-keys).

## Resolve all flags for a record

```bash theme={null}
GET /api/flags/:recordId
Authorization: Bearer <api-key>
```

Pass the record's full prefixed ID (e.g. `org-0ujsswThIGTUYm2K8FjOOfXtY1K`) as the path parameter. The API key must belong to the same project that owns the record — requests referencing records from other projects return a `404`.

**Example request:**

```bash theme={null}
curl https://swisstools.dev/api/flags/org-0ujsswThIGTUYm2K8FjOOfXtY1K \
  -H "Authorization: Bearer fk_2a9bX1c0d3e4f5g6h7i8j9k0"
```

**Example response:**

```json theme={null}
{
  "recordId": "org-0ujsswThIGTUYm2K8FjOOfXtY1K",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" },
  "flags": {
    "advanced-reporting": {"enabled": true, "rollout": 100, "source": "record"},
    "api-access": {"enabled": false, "rollout": 0, "source": "group-default"},
    "new-dashboard": {"enabled": true, "rollout": 50, "source": "group-default"}
  }
}
```

The `flags` object maps each group flag key to its resolved value:

* `enabled` is the **final** decision — the server applies the rollout dice-roll for you, so if the flag is on but the record falls outside the rollout, `enabled` is `false`.
* `rollout` is the configured rollout percentage (`0`–`100`).
* `source` is `"record"` when the value comes from a per-record override, or `"group-default"` when it falls back to the group flag's default.

Per-record overrides are applied automatically — if a record has an explicit value set for a flag, that value is returned; otherwise the group flag's default is used.

Pass an optional `?env=` query parameter (the environment's `key` or `name`) to resolve flags for a specific environment; when omitted, the project's default environment is used. If the value doesn't match any environment, `environment` is `null` and `flags` is `{}`.

## TypeScript integration

```typescript theme={null}
type ResolvedFlag = {
  enabled: boolean;
  rollout: number;
  source: "record" | "group-default";
};
type FlagResult = {
  recordId: string;
  projectId: string;
  environment: { id: string; name: string; key: string } | null;
  flags: Record<string, ResolvedFlag>;
};

async function getFeatureFlags(
  recordId: string,
  apiKey: string
): Promise<FlagResult> {
  const response = await fetch(`https://swisstools.dev/api/flags/${recordId}`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch flags: ${response.status}`);
  }

  return response.json() as Promise<FlagResult>;
}

// Usage
const result = await getFeatureFlags(
  "org-0ujsswThIGTUYm2K8FjOOfXtY1K",
  process.env.SWISSTOOLS_API_KEY!
);

if (result.flags["advanced-reporting"]?.enabled) {
  // show advanced reporting UI
}

if (result.flags["api-access"]?.enabled) {
  // enable API access features
}
```

## Check a single global flag

If you need to check one global flag rather than resolving a full record, use the check endpoint documented in [Global Flags](/feature-flags/global-flags). Like every project-scoped endpoint, it accepts either your API key or a dashboard session:

```bash theme={null}
# Check a single global flag
GET /api/projects/:projectId/flags/check/:flagKey
Authorization: Bearer <api-key>
```

It returns the resolved flag for the project's default environment (or the `?env=` you pass):

```json theme={null}
{
  "enabled": true,
  "rollout": 75,
  "source": "global",
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" }
}
```

Here `source` is `"cache"` when the result was served from the 60-second Redis cache, or `"global"` when freshly computed. As with the SDK endpoint, `enabled` already reflects the rollout roll.