Testing the API

This guide covers how to test and explore the Feature Management API using common API testing tools.

Postman collection

We provide a Postman collection for testing the Feature Management API.

Import the collection

Download the collection using the link above, or import directly in Postman using:

https://raw.githubusercontent.com/cloudbees-oss/fm-api-postman/main/cloudbees-fm-api.postman_collection.json▼

Open Postman and select Import.
Paste the URL or select the downloaded file.
The collection appears in your Postman sidebar.

Configure authentication

Before making requests, configure your API token:

In Postman, select the collection.
Go to the Authorization tab.
Set Type to Bearer Token.
Enter your API token in the Token field.

Use Postman environments to manage tokens for different environments (development, staging, production).

Collection structure

The collection is organized by resource type:

Feature Management API/
├── Flags/
│   ├── List flags
│   ├── Create flag
│   ├── Get flag by ID
│   ├── Get flag by name
│   ├── Update flag
│   ├── Delete flag
│   └── Restore flag
├── Flag Configurations/
│   ├── Get configuration
│   ├── Update configuration
│   ├── Patch configuration
│   └── Clone configuration
├── Target Groups/
│   ├── List target groups
│   ├── Create target group
│   ├── Get target group
│   ├── Update target group
│   └── Delete target group
└── Custom Properties/
    ├── List properties
    ├── Create property
    ├── Get property
    ├── Update property
    └── Delete property▼

Environment variables

Set these variables in your Postman environment:

Variable Description Example

Variable	Description	Example
`baseUrl`	API base URL	`https://api.cloudbees.io`
`applicationId`	Your FM application ID	`a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1`
`apiToken`	Your API bearer token	`eyJhbGciOiJ…`

baseUrl

API base URL

https://api.cloudbees.io

applicationId

Your FM application ID

a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1

apiToken

Your API bearer token

eyJhbGciOiJ…

Using curl

For quick testing from the command line, use curl:

List flags

curl -X GET \
  "https://api.cloudbees.io/v2/applications/${APP_ID}/flags" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json"▼

Create a flag

curl -X POST \
  "https://api.cloudbees.io/v2/applications/${APP_ID}/flags" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default.myNewFlag",
    "description": "My new feature flag",
    "flagType": "Boolean"
  }'▼

Get flag configuration

curl -X GET \
  "https://api.cloudbees.io/v2/applications/${APP_ID}/flags/${FLAG_ID}/configuration/environments/${ENV_ID}" \
  -H "Authorization: Bearer ${API_TOKEN}"▼

Update flag configuration

curl -X PUT \
  "https://api.cloudbees.io/v2/applications/${APP_ID}/flags/${FLAG_ID}/configuration/environments/${ENV_ID}" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "defaultValue": false,
    "conditions": [
      {
        "group": {
          "name": "BetaUsers"
        },
        "value": true
      }
    ]
  }'▼

Using HTTPie

HTTPie provides a more user-friendly command-line experience:

Installation

# macOS
brew install httpie

# Linux
apt install httpie

# pip
pip install httpie▼

Examples

# List flags
http GET "https://api.cloudbees.io/v2/applications/${APP_ID}/flags" \
  "Authorization: Bearer ${API_TOKEN}"

# Create a flag
http POST "https://api.cloudbees.io/v2/applications/${APP_ID}/flags" \
  "Authorization: Bearer ${API_TOKEN}" \
  name="default.newFlag" \
  description="New feature" \
  flagType="Boolean"▼

Shell script helpers

Create a helper script for common operations:

#!/bin/bash
# fm-api.sh - Feature Management API helper

API_BASE="https://api.cloudbees.io/v1"
APP_ID="${FM_APP_ID}"
TOKEN="${FM_API_TOKEN}"

function fm_list_flags() {
  curl -s -X GET \
    "${API_BASE}/applications/${APP_ID}/flags" \
    -H "Authorization: Bearer ${TOKEN}" | jq
}

function fm_get_flag() {
  local flag_id=$1
  curl -s -X GET \
    "${API_BASE}/applications/${APP_ID}/flags/${flag_id}" \
    -H "Authorization: Bearer ${TOKEN}" | jq
}

function fm_enable_flag() {
  local flag_id=$1
  local env_id=$2
  curl -s -X PUT \
    "${API_BASE}/applications/${APP_ID}/flags/${flag_id}/configuration/environments/${env_id}/configstate" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"enabled": true}' | jq
}

# Usage:
# export FM_APP_ID="your-app-id"
# export FM_API_TOKEN="your-token"
# source fm-api.sh
# fm_list_flags
# fm_get_flag "f7d3c8a1-4b2e-5f9a-b6c4-e1d8f3a7b5c2"
# fm_enable_flag "f7d3c8a1-4b2e-5f9a-b6c4-e1d8f3a7b5c2" "env-prod"▼

Response handling

Successful responses

Successful API calls return HTTP 200 with JSON data:

{
  "flag": {
    "id": "f7d3c8a1-4b2e-5f9a-b6c4-e1d8f3a7b5c2",
    "name": "default.myFlag",
    "flagType": "Boolean"
  }
}▼

Error responses

Errors return an error object with details:

{
  "code": 3,
  "message": "Invalid flag name format",
  "details": []
}▼

Common status codes

Code Description

Code	Description
`200`	Success
`400`	Bad request - check parameters
`401`	Unauthorized - check token
`403`	Forbidden - insufficient permissions
`404`	Not found - resource doesn’t exist
`429`	Rate limited - slow down requests

200

Success

400

Bad request - check parameters

401

Unauthorized - check token

403

Forbidden - insufficient permissions

404

Not found - resource doesn’t exist

429

Rate limited - slow down requests

Debugging tips

Verbose output with curl

curl -v -X GET \
  "https://api.cloudbees.io/v2/applications/${APP_ID}/flags" \
  -H "Authorization: Bearer ${API_TOKEN}"▼

Pretty print JSON

# Using jq
curl -s ... | jq

# Using Python
curl -s ... | python -m json.tool▼

Check token validity

If you receive 401 errors, verify your token:

Check the token hasn’t expired.
Verify the token has FM permissions.
Ensure you’re using the correct environment.

Testing the API

Postman collection

Import the collection

Configure authentication

Collection structure

Environment variables

Using curl

List flags

Create a flag

Get flag configuration

Update flag configuration

Using HTTPie

Installation

Examples

Shell script helpers

Response handling

Successful responses

Error responses

Common status codes

Debugging tips

Verbose output with curl

Pretty print JSON

Check token validity

Next steps