Export flag configurations as JSON and import them into other environments or projects
Last updated November 14, 2026
Import & Export
Flaggr supports exporting flag configurations as JSON and importing them into other environments, services, or projects. Use this for environment promotion, backup, migration, and infrastructure-as-code workflows.
Export Flags
Export by Project
Export all flags in a project:
curl -s "/api/flags/export?projectId=proj-123" \
-H "Authorization: Bearer fgr_your_token" \
-o flags-export.jsonFilter by Service or Environment
Narrow the export to a specific service and/or environment:
# Export only production flags for a specific service
curl -s "/api/flags/export?projectId=proj-123&serviceId=svc-web&environment=production" \
-H "Authorization: Bearer fgr_your_token" \
-o prod-flags.json
# Exclude disabled flags
curl -s "/api/flags/export?projectId=proj-123&includeDisabled=false" \
-H "Authorization: Bearer fgr_your_token" \
-o enabled-flags.jsonExport Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
projectId | string | required | Project to export from |
serviceId | string | all | Filter to a specific service |
environment | string | all | Filter to development, staging, or production |
format | string | json | Export format (currently only json) |
includeDisabled | string | true | Set to false to exclude disabled flags |
Export Format
The export JSON follows this schema:
{
"version": "1.0",
"exportedAt": "2026-02-21T12:00:00.000Z",
"projectId": "proj-123",
"flagCount": 3,
"flags": [
{
"key": "checkout-v2",
"name": "Checkout V2",
"description": "New streamlined checkout flow",
"type": "boolean",
"enabled": true,
"defaultValue": false,
"serviceId": "svc-web",
"environment": "production",
"tags": ["checkout"],
"variants": [],
"targeting": [
{
"id": "rule-1",
"conditions": [
{ "property": "plan", "operator": "equals", "value": "enterprise" }
],
"rolloutPercentage": 100,
"value": true
}
],
"isPublic": false
}
]
}Project-Level Export
You can also export an entire project (including services and metadata) via the project export endpoint:
curl -s "/api/projects/proj-123/export" \
-H "Authorization: Bearer fgr_your_token" \
-o project-export.jsonImport Flags
Basic Import
Import flags from a JSON payload:
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_your_token" \
-H "Content-Type: application/json" \
-d '{
"flags": [
{
"key": "checkout-v2",
"name": "Checkout V2",
"type": "boolean",
"enabled": false,
"defaultValue": false,
"serviceId": "svc-web",
"environment": "production"
}
],
"conflictResolution": "skip",
"dryRun": false
}'Conflict Resolution
When a flag with the same key, service, and environment already exists, the conflictResolution parameter controls behavior:
| Strategy | Behavior |
|---|---|
skip (default) | Leave the existing flag unchanged, increment skipped counter |
overwrite | Replace the existing flag with the file's item: its name, description, enabled, default, tags, variants and rules become what the item says, and what the item leaves out is cleared (enabled becomes false, as POST /api/flags reads a missing one; POST /api/flags/import also resets isPublic to private). The flag's type, overrides and prerequisites stay as they are |
error | Add an error to the errors array, skip this flag |
Neither import changes an existing flag's type (POST /api/flags/import, POST /api/projects/{id}/import). With overwrite, an item whose type differs from the stored flag's is refused with code: FLAG_TYPE_MISMATCH (Flag "checkout-v2" has type string in production, and the file gives it type boolean: an import can't change a flag's type. Import it with type string, or delete the flag first.), dry runs included, and nothing is written; the rest of the import goes ahead. The project import lists the refusal in errors with type: "flag", name, environment and code. The check comes after the access and approval checks, so a caller who can't write the flag is answered with that refusal instead (the project import's FORBIDDEN; the flags import's Forbidden: no write access to this scope) and never learns the flag's type, and before the live rollout plan check, so a dry run and a real run agree.
A file that lists one flag (the same key and environment) twice is settled by conflictResolution as a stored flag would be, dry runs included: the repeat is skipped (skip), listed in errors as Flag already exists: <key> (<environment>) (error), or overwrites the first item (overwrite; refused with FLAG_TYPE_MISMATCH if its type differs).
Dry Run
Set dryRun: true to validate the import without making any changes. The response shows exactly what would happen:
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_your_token" \
-H "Content-Type: application/json" \
-d '{
"flags": [...],
"conflictResolution": "overwrite",
"dryRun": true
}'Response:
{
"success": false,
"dryRun": true,
"total": 5,
"created": 3,
"updated": 1,
"skipped": 0,
"errors": [
{ "key": "1st-flag", "error": "Flag key must start with a letter and contain only letters, numbers, hyphens, and underscores" }
]
}Always run a dry run first when importing to a production project. It validates all flags and reports exactly what will change without modifying any data.
A dry run runs the checks of the real run on the flag as it would be written, and keeps what the file itself would do to a flag. For an overwrite, the flag as written includes its own overrides and prerequisites, which an import keeps: the item and the stored flag can each fit the data plane's per-flag limits (10,000 JSON values, for example) and not together. Then the dry run lists the item with code: FLAG_NOT_SERVABLE, as the real run does, instead of reporting it as updated. A flag that two items of the file name is created by the first and settled by conflictResolution for the second (skipped, listed in errors, overwritten, or refused for its type), in the dry run as in the real run; in a project import that also holds when two entries of the file name the same existing service (names match case-insensitively, as when two exports are merged into one file), and a second overwrite of a flag is checked over the row the first one leaves. For the same stored flags, a dry run and a real run of the same file report the same result for every item. (Only a real run takes a flag's rollout lock, so only a real run can answer BUSY because another change holds it.)
Import Response
| Field | Type | Description |
|---|---|---|
success | boolean | true if no errors occurred |
dryRun | boolean | Whether this was a dry run |
total | number | Total flags in the import payload |
created | number | Flags that were newly created |
updated | number | Flags that were overwritten (only with overwrite strategy) |
skipped | number | Flags that were skipped (existing flag, skip strategy) |
errors | array | Per-flag validation or import errors |
Project-Level Import
Import a full project export (services + flags). The route reads the export from data, so the file is wrapped:
jq '{data: ., conflictResolution: "skip", dryRun: true}' project-export.json |
curl -X POST /api/projects/proj-123/import \
-H "Authorization: Bearer fgr_your_token" \
-H "Content-Type: application/json" \
--data-binary @-Pipe the body to curl as above (--data-binary @-) instead of passing it as -d "$(jq …)": the operating system refuses a single command-line argument of more than about 128 KiB on Linux (1 MiB on macOS), and an export can be larger. The body is { "data": <the export file>, "conflictResolution": "skip" | "overwrite" | "error", "dryRun": true | false }; the export file on its own gets 400 with Invalid import data: missing services array. Services are matched by name, ignoring case, against the services the project has when the import starts: an export's service whose name the project doesn't have yet is created, so to copy a service, rename it in the file first. A file lists each service once, as an export does. If it lists one twice, both entries apply to the project's service in file order, and a flag under both is settled like a repeated flag (above), dry runs included; a service the project doesn't have yet is created once per entry. Set dryRun to false, or leave it out, to apply.
Each flag is checked like a single create or update. You need write access to its service in that environment (code: FORBIDDEN). Protected environments that require approval are refused per flag (code: APPROVAL_REQUIRED), because an import can't open change requests; change those flags in the dashboard or through the flag API. Overwrites are written under the flag's rollout lock: overwriting a flag that a live rollout plan manages is refused (code: ROLLOUT_IN_PROGRESS, or BUSY when another change holds the lock), and rollout-engine rules (rollout-<uuid>) in the file are never imported, on create or overwrite. Dry runs read the service's existing flags, so they report overwrites, skips and these refusals like a real run. That includes FLAG_NOT_SERVABLE for an overwrite whose item and the flag's own overrides together exceed the data plane's limits, and the flags an earlier entry of the same file creates or overwrites when the file lists a service twice. Refused flags appear in errors with code and environment, dry runs included. If Flaggr can't check which environments are protected, the import returns 503 with code: APPROVAL_CHECK_UNAVAILABLE and writes nothing. New flags with a reserved key are refused too (see Validation Rules). POST /api/migrate/launchdarkly applies the same checks; its preview lists them under refusals, and refused flags appear in failures when applying.
POST /api/flags/import follows the same rules per item: approval-required items come back in errors with code: "APPROVAL_REQUIRED", overwrites of a flag a live rollout plan manages with code: "ROLLOUT_IN_PROGRESS", new flags with a reserved key with code: "FLAG_KEY_RESERVED", and rollout-engine rules (rollout-<uuid>) in the file aren't imported.
Validation Rules
Every imported flag is validated before creation. Flags that fail validation are added to the errors array.
| Rule | Constraint |
|---|---|
| Flag key format | Must match ^[a-zA-Z][a-zA-Z0-9_-]*$ and be at most 100 characters, as for POST /api/flags; a longer key is refused with Flag key must be 100 characters or less |
| Flag key | Required |
| Flag name | Required: a string of 1 to 200 characters, as for POST /api/flags; a longer name is refused with Flag name must be 200 characters or less |
| Description | Optional: a string of at most 1,000 characters (Description must be 1000 characters or less); null counts as left out |
| Service ID | Required, must reference an existing service |
| Flag type | Must be boolean, string, number, or object |
| Environment | Must be development, staging, or production |
| Enabled | true or false. Left out, it is false, as in POST /api/flags (so an overwrite of an item without it switches the flag off); an import also reads null as left out, which POST /api/flags refuses. Anything else is refused with Enabled must be true or false |
Public (isPublic, POST /api/flags/import only) | true or false; left out or null, the flag is private (an overwrite resets it). Anything else is refused with isPublic must be true or false. The project import doesn't write it |
| Default value | Required, must match the declared flag type (see Type-Value Validation) |
| Batch size | Maximum 100 flags per import request |
| Request size | The 256 KB limit of POST /api/flags and PATCH /api/flags/{key} applies to one request, not to a flag: a flag that several updates have grown past it still exports and imports. Both imports cap the whole request at 25 MiB (26,214,400 bytes) and answer 413 over it (the project import checks your access to the project first, so a caller who can't write it gets the access error for any size); on flaggr.dev the hosting platform's own limit applies first (see Request Size Limits) |
| Reserved keys | A new flag can't be keyed bulk, create-from-nl, evaluate, evaluate-debug, export, import or stream |
| Targeting rules | Checked as POST /api/flags checks them: at most 100 rules, each an object of the documented shape (an id, conditions with a known operator), rolloutPercentage a whole number from 0 to 100, and every condition group with at least one condition |
| Variants | At most 50, each with a name; weight a whole number from 0 to 100 |
| Tags | At most 20, each a string of 1 to 50 characters |
| Schedule days | A rule schedule's recurrence.daysOfWeek are whole numbers from 0 (Sunday) to 6, at most 7 of them |
| Data plane limits | The flag as it would be stored must also be one https://api.flaggr.dev can load. The checks above catch most of its limits first; what they don't express, such as at most 10,000 conditions or 10,000 JSON values across the flag's values, is refused with code: FLAG_NOT_SERVABLE |
The reserved keys name built-in /api/flags/<segment> routes. A new flag with one is reported in errors with code: FLAG_KEY_RESERVED, dry runs included, and the rest of the import goes ahead. An existing flag with such a key can still be overwritten.
An import checks the fields it writes (the key, name, description, type, enabled, default, environment, tags, variants and targeting, and isPublic in POST /api/flags/import) as POST /api/flags does, except that it takes only the three environments above, and ignores the rest of an item. An item's overrides, prerequisites and projectId are never written (a new flag has none, an overwrite keeps the flag's own, and the project is the service's), so they are not checked and can't refuse an item; an export doesn't carry them either. The project export and import leave isPublic out: a flag the project import creates is private, and an overwrite keeps the flag's own setting. A null in description, enabled or isPublic counts as not set, like the other nulls an import accepts (listed below).
A flag whose targeting rules or variants fail is listed in errors with the first problem and its path (targeting[0].rolloutPercentage: Rollout percentage must be a whole number (0-100)), dry runs included, and isn't written. The data plane behind https://api.flaggr.dev can't load a fractional percentage or weight, or a targeting entry that isn't an object or null (a string, number, boolean or list): one stored would make it answer 503 for every flag of that service and environment. POST /api/migrate/launchdarkly checks the flags it maps the same way, and refuses one that fails with code: VALIDATION_ERROR.
Tags are checked the same way (an import used to store them as sent): more than 20, or one that isn't a string of 1 to 50 characters, fails the item with tags: Maximum 20 tags allowed (for a bad tag, its path, such as tags[1], and what's wrong). The LaunchDarkly migration keeps the first 20 tags that fit and lists the rest in its warnings. A null in an optional field counts as not set (exports of flags stored by older builds carry them): in the variants, targeting and tags lists themselves; in a rule's conditions, conditionOperator, groups, groupOperator, rolloutPercentage, variant and schedule (and the schedule's own fields); and in a condition's cohortId and a variant's weight. A rule's or variant's value is never touched.
Flags the Data Plane Can't Load
https://api.flaggr.dev loads a service's flags in one environment as a single snapshot, so one flag it can't load makes it answer 503 for every flag of that service and environment. So an import refuses a flag the data plane couldn't load, in one of two ways:
- The checks in the table above catch most of its limits first: more than 100 rules, 50 variants or 20 tags, and a rollout percentage, variant weight or schedule day that isn't a whole number. The item is listed in
errorswith the first problem and its path, and nocode. - What those checks don't express is listed with
code: FLAG_NOT_SERVABLE: more than 10,000 conditions or 1,000 condition groups, more than 10,000 JSON values across the flag's values (a clause that lists 10,000 values is over the limit once the rest of the flag counts), and values nested more than 64 deep.
Dry runs report both, and the rest of the import goes ahead. An overwrite is checked a second time, as the row it leaves: the item's content over the flag's own overrides and prerequisites, which stay. The two can each be within the limits and together over them; then the item is refused with FLAG_NOT_SERVABLE, in a dry run as in a real one. A FLAG_NOT_SERVABLE item looks like this:
{
"key": "allow-list",
"code": "FLAG_NOT_SERVABLE",
"error": "Flag \"allow-list\" can't be saved: the evaluation API couldn't load it (targeting[0].conditions[0].value exceeds dynamic JSON nodes). One flag it can't load stops every flag of its service in production from evaluating there."
}The project import (POST /api/projects/{id}/import) reports the same refusal, and the LaunchDarkly migration lists it under refusals in its preview and failures when it applies (for instance a clause that lists 10,000 values or more). The migration refuses a mapped flag whose default isn't a value of its type with code: VALIDATION_ERROR, in the preview too (it takes the type from the flag's kind or the first variation, and each environment's default from its off variation or its fallthrough; Migrate from LaunchDarkly has the mapping). It holds the flag's key, environment, name, description and on to the flag API's rules too (Migrate from LaunchDarkly lists them). A LaunchDarkly flag with more than 5,000 targeted users needs more than the 50 overrides a flag takes and is refused (VALIDATION_ERROR); the migration's warnings say how many overrides its targets need. See Refused Flag Writes for every route that checks.
Type-Value Validation
The default value must match the flag type:
| Type | Valid | Invalid |
|---|---|---|
boolean | true, false | "true", 1 |
string | "hello" | true, 42 |
number | 42, 3.14 | "42", true |
object | {"key": "value"} | null, [1, 2], "string" |
Common Workflows
Environment Promotion
Move flags from staging to production:
# 1. Export from staging
curl -s "/api/flags/export?projectId=proj-123&environment=staging" \
-H "Authorization: Bearer fgr_token" \
-o staging-flags.json
# 2. Update the environment field in the export
jq '.flags |= map(.environment = "production" | .enabled = false)' \
staging-flags.json > production-flags.json
# 3. Dry run the import
jq '{flags: .flags, conflictResolution: "skip", dryRun: true}' production-flags.json |
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_prod_token" \
-H "Content-Type: application/json" \
--data-binary @-
# 4. Execute the import
jq '{flags: .flags, conflictResolution: "skip", dryRun: false}' production-flags.json |
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_prod_token" \
-H "Content-Type: application/json" \
--data-binary @-Backup and Restore
# Backup
curl -s "/api/flags/export?projectId=proj-123" \
-H "Authorization: Bearer fgr_token" \
-o "backup-$(date +%Y%m%d).json"
# Restore (overwrite existing flags)
jq '{flags: .flags, conflictResolution: "overwrite"}' backup-20260221.json |
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_token" \
-H "Content-Type: application/json" \
--data-binary @-Cross-Project Migration
Export from one project and import into another by updating service IDs:
# Export from source project
curl -s "/api/flags/export?projectId=proj-old" \
-H "Authorization: Bearer fgr_old_token" \
-o source-flags.json
# Update serviceId to match the target project's services
jq '.flags |= map(.serviceId = "new-svc-id")' source-flags.json > target-flags.json
# Import into target project
jq '{flags: .flags, conflictResolution: "error"}' target-flags.json |
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_new_token" \
-H "Content-Type: application/json" \
--data-binary @-Related
- Flag Lifecycle — Planning and retiring flags
- Versioning — Track every change with rollback
- Infrastructure as Code — Automate flag management in CI/CD
- API Tokens — Authentication for import/export operations
- REST API Reference — Complete endpoint reference