featbit-rest-api

name	featbit-rest-api
description	Expert guidance for using the FeatBit REST API to manage projects, environments, and feature flags programmatically. Use when user asks about "FeatBit API", "REST API", "create project API", "create environment API", "create feature flag API", "API authentication", "OpenAPI key", or needs to automate FeatBit operations via HTTP endpoints. Do not use for SDK integration, deployment configuration, or flag evaluation questions. Use when this capability is needed.
metadata	{"author":"featbit"}

FeatBit REST API

Expert guidance for interacting with FeatBit services through the REST API. Use these endpoints to manage projects, environments, feature flags, and more programmatically.

When to Use This Skill

Activate when users:

• Need to call FeatBit management APIs (projects, environments, flags)
• Ask about API authentication (JWT Bearer or OpenAPI Key)
• Want to automate FeatBit resource creation via scripts or CI/CD
• Need API request/response formats and error handling
• Ask about specific endpoint URLs, parameters, or payloads

Base URL and Versioning

https://your-featbit-instance.com/api/v{version}

• Current Version: v1 (URL pattern: /api/v1/{resource})
• Replace your-featbit-instance.com with your actual FeatBit host

Authentication

FeatBit supports two authentication methods:

1. JWT Bearer Token (User Authentication)

Authorization: Bearer {jwt_token}

Best for: interactive sessions, user-scoped operations.

2. OpenAPI Key (Machine-to-Machine)

Authorization: {api_key}

Best for: CI/CD pipelines, automation scripts, service-to-service calls.

Detailed Guide: references/authentication.md

Response Format

All API responses follow a standardized wrapper:

{
  "success": true,
  "data": { ... },
  "errors": []
}

On failure:

{
  "success": false,
  "data": null,
  "errors": [
    { "code": "Required:name", "message": "The name field is required" }
  ]
}

Common HTTP Status Codes

Code	Description
200	Success
400	Bad Request — validation errors
401	Unauthorized — missing or invalid authentication
403	Forbidden — insufficient permissions
404	Not Found — resource doesn't exist
500	Internal Server Error

API Endpoints

Project Management

Method	Endpoint	Description	Permission
GET	/api/v1/projects	List all projects in the organization	CanAccessProject
POST	/api/v1/projects	Create a new project	CreateProject
GET	/api/v1/projects/{projectId}	Get project details with environments	CanAccessProject

Quick example — Create a project:

curl -X POST "https://your-featbit-instance.com/api/v1/projects" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"name": "E-Commerce Platform", "key": "ecommerce"}'

• Auto-generates two environments: Prod and Dev
• Each environment gets a Server Key and Client Key

Full Reference: references/projects-api.md

Environment Management

Method	Endpoint	Description	Permission
POST	/api/v1/projects/{projectId}/envs	Create a new environment	CreateEnv

Quick example — Create an environment:

curl -X POST "https://your-featbit-instance.com/api/v1/projects/{projectId}/envs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"name": "Staging", "key": "staging", "description": "QA environment"}'

• Auto-generates Server Key and Client Key
• Key must be unique within the project

Full Reference: references/environments-api.md

Feature Flag Management

Method	Endpoint	Description	Permission
POST	/api/v1/envs/{envId}/feature-flags	Create a new feature flag	CreateFlag

Quick example — Create a boolean feature flag:

curl -X POST "https://your-featbit-instance.com/api/v1/envs/{envId}/feature-flags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{
    "name": "New Checkout Flow",
    "key": "new-checkout-flow",
    "isEnabled": false,
    "variationType": "boolean",
    "variations": [
      {"id": "var-on", "name": "On", "value": "true"},
      {"id": "var-off", "name": "Off", "value": "false"}
    ],
    "enabledVariationId": "var-on",
    "disabledVariationId": "var-off",
    "tags": ["checkout"]
  }'

• Supports variation types: boolean, string, number, json
• Key pattern: ^[a-zA-Z0-9._-]+$

Full Reference: references/feature-flags-api.md

Workflow Example

A typical setup flow — create project, add environment, create flag:

# 1. Create a project (auto-creates Prod and Dev environments)
PROJECT=$(curl -s -X POST "$BASE_URL/api/v1/projects" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"My App","key":"my-app"}')

PROJECT_ID=$(echo $PROJECT | jq -r '.data.id')
DEV_ENV_ID=$(echo $PROJECT | jq -r '.data.environments[1].id')

# 2. (Optional) Create a staging environment
curl -s -X POST "$BASE_URL/api/v1/projects/$PROJECT_ID/envs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"Staging","key":"staging","description":"QA environment"}'

# 3. Create a feature flag in the dev environment
curl -s -X POST "$BASE_URL/api/v1/envs/$DEV_ENV_ID/feature-flags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name":"New Feature","key":"new-feature","isEnabled":false,
    "variationType":"boolean",
    "variations":[{"id":"v1","name":"On","value":"true"},{"id":"v2","name":"Off","value":"false"}],
    "enabledVariationId":"v1","disabledVariationId":"v2","tags":["backend"]
  }'

More Patterns: references/common-patterns.md

Best Practices

1. Key Naming: Use descriptive, kebab-case keys (e.g., new-checkout-flow)
2. Variation IDs: Use GUIDs or unique strings to avoid collisions
3. Tags: Organize flags by feature, team, or category
4. Secrets: Store API keys securely; never commit them to version control
5. Test First: Always test API calls in a development environment before production
6. Environments: Maintain separate environments for dev, staging, and production

Reference Guides

• references/authentication.md — JWT vs OpenAPI Key, obtaining tokens
• references/projects-api.md — Create project, get project (full request/response)
• references/environments-api.md — Create environment (full request/response)
• references/feature-flags-api.md — Create feature flag, variation types, targeting
• references/common-patterns.md — Workflow examples, error codes, variation types reference

Official Resources

• Interactive API Docs: https://app-api.featbit.co/docs/index.html
• OpenAPI Schema: https://app-api.featbit.co/swagger/OpenApi/swagger.json

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.