Experiments API

A Experiments API expõe os mesmos experimentos canary e shadow gerenciados no dashboard Zeus, atrás de um contrato estável. Três endpoints: listar, criar e fazer rollback.

Todos os endpoints de escrita exigem o header de segurança X-Floopy-Confirm: experiments. Esta é uma porta deliberada e de baixo custo (sem novo escopo de auth) que bloqueia abuso acidental e oportunista a partir de uma key vazada.

Autenticação e gating (todos os três endpoints)

Authorization: Bearer <your-floopy-api-key>

Permissão: read_permission para GET, write_permission para POST.
Plano: Apenas Pro (has_test_ab).
Atrás do kill switch de canary por organização.

GET /v1/experiments

Lista os experimentos da organização do chamador.

Endpoint

GET https://api.floopy.ai/v1/experiments

Resposta (200)

[
  {
    "id": "5b3f9c1e-7a2b-4c3d-9e1f-0a1b2c3d4e5f",
    "type": "canary",
    "status": "active",
    "traffic_pct": 5,
    "baseline":  { "provider": "openai", "model": "gpt-5.4" },
    "candidate": { "provider": "openai", "model": "gpt-5.4-mini" },
    "started_at": "2026-05-04T09:00:00Z",
    "ended_at":   null,
    "summary":    null
  }
]

Field	Type	Description
`id`	UUID	Id do experimento.
`type`	string	`canary` ou `shadow`.
`status`	string	`draft`, `active`, `completed`, ou `rolled_back`.
`traffic_pct`	number	Percentual de tráfego elegível direcionado ao candidato (`0..=100`).
`baseline.provider`, `baseline.model`	string	O lado de controle.
`candidate.provider`, `candidate.model`	string	O lado da variante.
`started_at`	ISO8601 \| null	Quando o experimento foi ativado.
`ended_at`	ISO8601 \| null	Quando o experimento terminou (ou sofreu rollback).
`summary`	object \| null	Sumário agregado de qualidade e custo, populado após o fim do experimento.

Erros

Status	Code	Quando
`403`	`read_permission` / `plan_required`	Permissão ou flag de plano ausente.
`5xx`	`internal`	Falha upstream.

Exemplo curl

curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
  "https://api.floopy.ai/v1/experiments" | jq .

POST /v1/experiments

Cria um novo experimento canary ou shadow. Limite do body: 8 KiB.

Endpoint

POST https://api.floopy.ai/v1/experiments

Headers obrigatórios

Authorization: Bearer <your-floopy-api-key>
Content-Type: application/json
X-Floopy-Confirm: experiments

Request body

{
  "type": "canary",
  "baseline":  { "provider": "openai", "model": "gpt-5.4" },
  "candidate": { "provider": "openai", "model": "gpt-5.4-mini" },
  "traffic_pct": 5,
  "stop_rule": { "max_regression": 0.02, "min_n": 200 }
}

Field	Type	Required	Constraints
`type`	string	Yes	`canary` ou `shadow`.
`baseline.provider`	string	Yes	Id de provider existente.
`baseline.model`	string	Yes	Id de modelo existente.
`candidate.provider`	string	Yes	Id de provider existente. Deve diferir do par baseline.
`candidate.model`	string	Yes	Id de modelo existente.
`traffic_pct`	number	Yes	`0..=100`.
`stop_rule.max_regression`	number	No	Teto de queda da qualidade composta, `[0, 0.5]`.
`stop_rule.min_n`	integer	No	Contagem mínima de amostras antes que o experimento possa completar.

O body é deny_unknown_fields — chaves desconhecidas retornam 400 invalid_body.

Resposta (201)

Retorna a linha criada, formato idêntico ao item do GET.

Erros

Status	Code	Quando
`400`	`missing_confirmation`	`X-Floopy-Confirm: experiments` ausente ou com valor errado.
`400`	`invalid_body`	Falha na validação de schema, ou chaves desconhecidas.
`400`	`invalid_traffic_pct`	`traffic_pct` fora de `[0, 100]`.
`403`	`write_permission` / `plan_required`	Permissão ou flag de plano ausente.
`409`	`active_already_exists`	Já existe um experimento ativo para o mesmo par `(baseline, candidate)`.
`429`	`rate_limited`	Acima do orçamento por organização.
`5xx`	`internal`	Falha upstream.

Exemplo curl

curl -s -X POST \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Floopy-Confirm: experiments" \
  -d '{
    "type": "canary",
    "baseline":  {"provider":"openai","model":"gpt-5.4"},
    "candidate": {"provider":"openai","model":"gpt-5.4-mini"},
    "traffic_pct": 5,
    "stop_rule": {"max_regression": 0.02, "min_n": 200}
  }' \
  "https://api.floopy.ai/v1/experiments"

POST /v1/experiments/`{id}`/rollback

Força um experimento em execução de volta para sua baseline imediatamente.

Endpoint

POST https://api.floopy.ai/v1/experiments/{id}/rollback

Headers obrigatórios

Authorization: Bearer <your-floopy-api-key>
X-Floopy-Confirm: experiments

Sem request body.

Resposta (200)

Retorna a linha do experimento no estado rolled_back. Idempotente — chamar rollback em um experimento já revertido retorna 200 com a linha existente, e não 409.

Erros

Status	Code	Quando
`400`	`missing_confirmation`	Header de confirmação ausente ou errado.
`403`	`write_permission` / `plan_required`	Permissão ou flag de plano ausente.
`404`	`not_found`	Nenhum experimento com esse id na organização do chamador. Bytes idênticos para consultas cross-tenant.
`409`	`completed_cannot_rollback`	O experimento já está `completed` e não pode sofrer rollback.
`5xx`	`internal`	Falha upstream.

Exemplo curl

EXP_ID="5b3f9c1e-7a2b-4c3d-9e1f-0a1b2c3d4e5f"
curl -s -X POST \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "X-Floopy-Confirm: experiments" \
  "https://api.floopy.ai/v1/experiments/$EXP_ID/rollback" | jq .

Trilha de auditoria

Todo evento do ciclo de vida do experimento (created, started, rolled_back, completed, error) é persistido em routing_experiment_events com actor_api_key_id. Estes eventos aparecem no sidecar do export de decisões e na página de Experimentos do Zeus. O evento de auditoria experiment_rolled_back nunca sofre throttle — todo rollback produz uma linha.

Veja também

GET /v1/constraints — defina o envelope de segurança que os experimentos devem respeitar.
GET /v1/decisions — consulte decisões individuais marcadas pelo id do experimento.

Experiments API

Autenticação e gating (todos os três endpoints)

GET /v1/experiments

Endpoint

Resposta (200)

Erros

Exemplo curl

POST /v1/experiments

Endpoint

Headers obrigatórios

Request body

Resposta (201)

Erros

Exemplo curl

POST /v1/experiments/{id}/rollback

Endpoint

Headers obrigatórios

Resposta (200)

Erros

Exemplo curl

Trilha de auditoria

Veja também

POST /v1/experiments/`{id}`/rollback