Export flag configurations as JSON and import them into other environments or projects

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 flg_your_token" \
  -o flags-export.json

Filter 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 flg_your_token" \
  -o prod-flags.json
 
# Exclude disabled flags
curl -s "/api/flags/export?projectId=proj-123&includeDisabled=false" \
  -H "Authorization: Bearer flg_your_token" \
  -o enabled-flags.json

Export 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": true,
      "serviceId": "svc-web",
      "environment": "production",
      "tags": ["checkout"],
      "variants": [],
      "targeting": [
        {
          "id": "rule-1",
          "conditions": [
            { "property": "plan", "operator": "equals", "value": "enterprise" }
          ],
          "rolloutPercentage": 100
        }
      ],
      "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 flg_your_token" \
  -o project-export.json

Import Flags

Basic Import

Import flags from a JSON payload:

curl -X POST /api/flags/import \
  -H "Authorization: Bearer flg_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`	Update the existing flag with the imported values
`error`	Add an error to the `errors` array, skip this flag

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 flg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "flags": [...],
    "conflictResolution": "overwrite",
    "dryRun": true
  }'

Response:

{
  "success": true,
  "dryRun": true,
  "total": 5,
  "created": 3,
  "updated": 1,
  "skipped": 0,
  "errors": [
    { "key": "bad-flag", "error": "Flag key must start with a letter" }
  ]
}

Info

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.

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):

curl -X POST /api/projects/proj-123/import \
  -H "Authorization: Bearer flg_your_token" \
  -H "Content-Type: application/json" \
  -d @project-export.json

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_-]*$`
Flag key	Required
Flag name	Required
Service ID	Required, must reference an existing service
Flag type	Must be `boolean`, `string`, `number`, or `object`
Environment	Must be `development`, `staging`, or `production`
Default value	Required, must match the declared flag type
Batch size	Maximum 100 flags per import request

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`, `"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 flg_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
curl -X POST /api/flags/import \
  -H "Authorization: Bearer flg_prod_token" \
  -H "Content-Type: application/json" \
  -d "$(jq '{flags: .flags, conflictResolution: "skip", dryRun: true}' production-flags.json)"
 
# 4. Execute the import
curl -X POST /api/flags/import \
  -H "Authorization: Bearer flg_prod_token" \
  -H "Content-Type: application/json" \
  -d "$(jq '{flags: .flags, conflictResolution: "skip", dryRun: false}' production-flags.json)"

Backup and Restore

# Backup
curl -s "/api/flags/export?projectId=proj-123" \
  -H "Authorization: Bearer flg_token" \
  -o "backup-$(date +%Y%m%d).json"
 
# Restore (overwrite existing flags)
curl -X POST /api/flags/import \
  -H "Authorization: Bearer flg_token" \
  -H "Content-Type: application/json" \
  -d "$(jq '{flags: .flags, conflictResolution: "overwrite"}' backup-20260221.json)"

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 flg_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
curl -X POST /api/flags/import \
  -H "Authorization: Bearer flg_new_token" \
  -H "Content-Type: application/json" \
  -d "$(jq '{flags: .flags, conflictResolution: "error"}' target-flags.json)"