Referência da API

Autenticação

Toda requisição à API deve incluir uma chave de API válida no header HTTP X-API-Key. As chaves têm o prefixo ff_live_ e são vinculadas a um projeto específico, garantindo que cada chave só enxergue as flags daquele projeto.

Nunca exponha a chave em código executado no navegador ou em repositórios públicos. Trate-a como uma credencial secreta e prefira injetá-la por variável de ambiente no seu backend. Requisições sem o header, ou com uma chave inválida ou revogada, recebem 401 Unauthorized.

X-API-Key: ff_live_xxxxxxxxxxxx

Avaliar uma flag (GET)

Para avaliar uma única flag, faça uma requisição GET para /api/evaluate informando o parâmetro key com a chave da flag e o parâmetro env com o ambiente desejado (por exemplo, production). A resposta traz o objeto data com a chave avaliada e o campo enabled indicando se a flag está ativa naquele ambiente.

GET /api/evaluate?key=nova-tela-login&env=production
X-API-Key: ff_live_xxxxxxxxxxxx

# 200 OK
{ "data": { "key": "nova-tela-login", "enabled": true } }

Avaliar em lote (POST)

Quando precisar avaliar várias flags de uma vez, envie uma requisição POST para /api/evaluate com um corpo JSON contendo o ambiente em env e a lista de chaves em keys. A resposta devolve um array em data, com um objeto por flag solicitada, preservando a ordem enviada. A avaliação em lote reduz o número de requisições e ajuda a manter o consumo dentro do rate limit.

POST /api/evaluate
X-API-Key: ff_live_xxxxxxxxxxxx
Content-Type: application/json

{ "env": "production", "keys": ["a", "b"] }

# 200 OK
{ "data": [ { "key": "a", "enabled": true }, { "key": "b", "enabled": false } ] }

Códigos de resposta

200 OK: a avaliação foi concluída e o corpo traz o resultado em data.

400 Bad Request: a requisição está malformada, por exemplo com parâmetros ausentes, ambiente inválido ou corpo JSON incorreto.

401 Unauthorized: o header X-API-Key está ausente, inválido ou foi revogado.

429 Too Many Requests: o rate limit da sua conta foi excedido. A resposta inclui o header Retry-After indicando, em segundos, quanto tempo esperar antes de tentar novamente.

Rate limit e cache

Os limites de uso variam conforme o plano. No plano FREE, a API aceita até 300 avaliações por dia. Nos planos PRO e TEAM, o limite sobe para até 10.000 requisições por minuto, atendendo cargas de produção de alto volume.

Para reduzir latência e consumo, as avaliações passam por um cache interno de 30 segundos: alterações feitas em uma flag podem levar até esse intervalo para se refletirem nas respostas da API. Ao exceder o limite, novas requisições recebem 429 até a janela ser renovada.

Próximos passos

Para começar a integrar, crie uma conta e gere uma chave de API para o seu projeto no painel.

Documentação geral

Se preferir explorar antes o restante da plataforma, consulte a documentação geral do Floating Flags.