Referencia de API

Lee tus feature flags por REST

La API de lectura de GreenFlags sirve los flags de un ambiente por HTTPS, evaluados en el edge. Cualquier lenguaje que pueda hacer un GET puede consumirla — sin SDK obligatorio.

Inicio rápido

1. Crea tu cuenta gratis — obtienes un workspace, un proyecto y tus ambientes.
2. En el dashboard: abre tu proyecto → elige un ambiente (ej. production) → API Tokens → crea un token.
3. Copia el token (gf_…) — se muestra una sola vez y se guarda hasheado de nuestro lado.
4. Llama a la API:

curl https://app.greenflags.dev/v1/flags \
  -H "Authorization: Bearer gf_tu_token_aqui"

Autenticación y tokens

Cada request se autentica con un Bearer token en el header Authorization.

• Los tokens tienen alcance de un solo ambiente. Un token de production solo puede leer flags de production — tus credenciales de staging nunca se cruzan con prod, ni al revés. Crea un token por ambiente.
• Se muestra una vez, se guarda hasheado. Si pierdes un token, revócalo en el dashboard y crea otro — la revocación es instantánea.
• Cuota mensual opcional por token. Puedes limitar cuántas lecturas hace un token al mes; el límite se aplica en el edge.
• Úsalo del lado servidor. Trátalo como una contraseña: backend, funciones serverless o pipeline de build — no lo incluyas en código público del navegador.

Listar todos los flags

Devuelve todos los flags activos del ambiente del token, con el tipo y el valor actual evaluado de cada uno.

curl https://app.greenflags.dev/v1/flags \
  -H "Authorization: Bearer $GREENFLAGS_TOKEN"

Respuesta 200:

{
  "success": true,
  "data": {
    "flags": [
      { "key": "new-checkout", "type": "boolean", "value": true },
      { "key": "banner-text", "type": "string", "value": "Oferta de verano" }
    ]
  }
}

Obtener un flag por su key

Devuelve un solo flag cuando únicamente necesitas un valor.

curl https://app.greenflags.dev/v1/flags/new-checkout \
  -H "Authorization: Bearer $GREENFLAGS_TOKEN"

Respuesta 200:

{
  "success": true,
  "data": {
    "flag": { "key": "new-checkout", "type": "boolean", "value": true }
  }
}

Tipos de flags

Cada flag guarda un valor independiente por ambiente — cambiarlo en production jamás toca staging.

Geocercas (geofencing)

Puedes delimitar un flag a un radio geográfico desde el dashboard. Un flag con geocerca incluye su centro y radio en metros:

{
  "key": "promo-tienda",
  "type": "boolean",
  "value": true,
  "geofence": {
    "latitude": 19.4326,
    "longitude": -99.1332,
    "radiusMeters": 1000
  }
}

Define las coordenadas del usuario final en un SDK oficial y la evaluación sucede localmente en tu aplicación — las coordenadas nunca se envían a GreenFlags. Dentro del radio, el flag conserva su valor normal; fuera devuelve false para flags booleanos y null para cualquier otro tipo. Los flags sin geocerca no cambian.

Despliegue por porcentaje y variantes

Desde el dashboard puedes liberar un flag gradualmente a un porcentaje de tus usuarios, o repartirlos entre variantes con pesos para pruebas A/B. Ambos se configuran por ambiente y se evalúan de forma determinista por usuario.

Resolver por usuario con ?user=

Ambos endpoints de lectura aceptan el parámetro opcional user — cualquier identificador estable del usuario final (id de usuario, email, id de dispositivo). Cuando está presente, la API asigna al usuario y devuelve solo el valor final:

curl "https://app.greenflags.dev/v1/flags?user=user-42" \
  -H "Authorization: Bearer $GREENFLAGS_TOKEN"

La asignación es determinista: un hash de {flagKey}:{userKey} ubica a cada usuario en un cubo del 0 al 99. El mismo usuario recibe siempre el mismo valor — en cada llamada, en cada SDK y en cada plataforma.

Despliegue por porcentaje

Un flag con despliegue al 30% sirve su valor almacenado a los usuarios en los cubos 0–29. El resto recibe el valor apagado: false para flags booleanos, null para string, number y json. Subir el porcentaje solo agrega usuarios — nadie que ya tenga la funcionalidad la pierde.

Variantes (pruebas A/B)

Las variantes reparten a los usuarios entre varios valores con nombre y pesos que suman como máximo 100. Si los pesos suman menos de 100, los usuarios restantes reciben el valor base del flag. Sin ?user=, la configuración cruda viene incluida en la respuesta:

{
  "key": "tema-checkout",
  "type": "string",
  "value": "clasico",
  "variants": [
    { "name": "A", "weight": 30, "value": "azul" },
    { "name": "B", "weight": 70, "value": "verde" }
  ]
}

Con ?user=, el servidor resuelve la variante y la respuesta trae solo el valor asignado — ej. { "key": "tema-checkout", "type": "string", "value": "azul" }. Un flag puede usar despliegue por porcentaje o variantes en un ambiente dado, nunca ambos a la vez.

Evaluación local en los SDKs

Sin ?user=, la respuesta incluye la configuración cruda de rollout / variants para que los SDKs oficiales evalúen localmente desde el snapshot en caché — sin requests extra por usuario. Los SDKs de cliente (JS/TS, React, Vue, Flutter) reciben la identidad una vez con setUser("user-42") (con id anónimo de respaldo); los SDKs de servidor (Go, PHP, Python) reciben el usuario por llamada, ej. GetFlagForUser("tema-checkout", "user-42").

Errores

Los errores siempre usan el mismo formato: { "success": false, "error": "CODIGO", "message": "…" }.

¿Prefieres un SDK?

Todos los SDKs envuelven esta misma API con el mismo modelo seguro para tu facturación: un request trae el ambiente completo y cada lectura posterior sale de memoria.

Ejemplo con el cliente TypeScript — tipos, caché de snapshots y cero dependencias:

import { GreenFlags } from "@greenflags/client";

const flags = new GreenFlags({ token: process.env.GREENFLAGS_TOKEN });

if (await flags.isEnabled("new-checkout")) {
  renderNewCheckout();
}

Y si trabajas con agentes de IA, el servidor @greenflags/mcp permite a los asistentes gestionar tus flags vía Model Context Protocol.