Projetos

Visão Geral

Projetos permitem segmentar seu tráfego de IA em grupos lógicos — por produto, funcionalidade, equipe ou qualquer outra dimensão que faça sentido para sua organização. Cada projeto possui suas próprias visualizações de dashboard, rastreamento de custos, métricas de qualidade, chaves de API e membros de equipe.

Quando uma requisição passa pelo gateway Floopy, ela é marcada com um ID de projeto. Esse ID flui até o ClickHouse, onde qualquer consulta de analytics pode ser filtrada por um único projeto ou comparada entre todos os projetos.

Conceitos Principais

Projetos são agnósticos a ambiente. O ambiente (development, staging, production, other) é uma propriedade da chave de API, não do projeto. Isso significa que um único projeto como “Checkout” pode ter chaves separadas para dev e prod, e o widget de custo por ambiente divide os gastos entre ambientes nativamente.

Toda organização tem um projeto Padrão. Criado automaticamente quando a organização é provisionada. Tráfego legado (requisições sem ID de projeto) é atribuído ao projeto Padrão.

O header floopy-project-id é opcional. Se sua chave de API está travada em um projeto, esse projeto é usado automaticamente. Caso contrário, o gateway resolve o projeto usando uma cadeia de fallback: header → projeto padrão da chave → projeto Padrão da organização.

Criando um Projeto

Crie projetos pelo dashboard em Projetos > Novo Projeto. Cada projeto possui:

• Nome — Nome de exibição (até 100 caracteres)
• Slug — Identificador URL-safe (letras minúsculas, números, hífens, até 63 caracteres)
• Descrição — Opcional, até 500 caracteres
• Cor e Ícone — Para identificação visual no dashboard

Cotas por Plano

Enviando o Header floopy-project-id

Envie um UUID de projeto no header floopy-project-id para marcar requisições com um projeto específico.

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-project-id: a1b2c3d4-5678-9abc-def0-123456789abc" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "floopy-project-id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    },
)

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-project-id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    },
  },
);

req, _ := http.NewRequest("POST", "https://api.floopy.ai/v1/chat/completions", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("FLOOPY_API_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("floopy-project-id", "a1b2c3d4-5678-9abc-def0-123456789abc")

resp, err := http.DefaultClient.Do(req)

Cadeia de Fallback

O gateway resolve o ID do projeto usando esta prioridade:

1. Chave travada — Se a chave de API tem um project_id definido, esse projeto é sempre usado. Um header floopy-project-id diferente do projeto travado retorna 403 Forbidden.
2. Header — O header floopy-project-id da requisição.
3. Padrão da chave — O campo default_project_id da chave de API.
4. Padrão da organização — O projeto Padrão da organização (UUID zero sentinel).

graph TD
    A[Requisição chega] --> B{Chave tem project_id?}
    B -->|Sim| C{Header confere?}
    C -->|Sim ou sem header| D[Usar projeto travado]
    C -->|UUID diferente| E[403 Forbidden]
    B -->|Não| F{Header presente?}
    F -->|Sim| G[Usar projeto do header]
    F -->|Não| H{Chave tem default_project_id?}
    H -->|Sim| I[Usar projeto padrão da chave]
    H -->|Não| J[Usar projeto Padrão da org]

Chaves de API por Projeto

Em vez de enviar o header floopy-project-id em toda requisição, você pode criar chaves de API travadas em um projeto. Toda requisição usando essa chave é automaticamente atribuída ao projeto travado — sem necessidade de header.

Esta é a abordagem recomendada para produção. Crie uma chave por projeto por ambiente:

Chaves travadas garantem isolamento de projeto no nível do gateway. Uma requisição que envia um header floopy-project-id diferente é rejeitada com 403 Forbidden.

Modelo de Ambientes

Ambientes são uma propriedade da chave de API. Ao criar ou editar uma chave, você pode opcionalmente definir seu ambiente como: development, staging, production ou other.

O ambiente é registrado em cada log de requisição. Isso permite:

• Filtrar visualizações do dashboard por ambiente
• Comparar custos entre ambientes para o mesmo projeto
• Definir limites de taxa (RPM) e tetos de custo mensal por ambiente

Limites de Ambiente

Configure limites de RPM e tetos de custo mensal em USD por ambiente em Configurações > Limites. Quando um teto de custo é excedido, o gateway retorna 402 Payment Required para todas as requisições usando chaves daquele ambiente até que o custo caia abaixo de 95% do limite (histerese de 5%).

Dashboards por Projeto

Ao selecionar um projeto no seletor de projetos, todas as páginas do dashboard (requisições, sessões, usuários, propriedades, cache, rate limits, segurança, avaliações) são filtradas para mostrar apenas os dados daquele projeto.

No modo de projeto único, cinco widgets adicionais aparecem:

• Comparação de Custo — Custo por milhão de tokens do projeto vs. média da organização
• Comparação de Qualidade — Score de feedback vs. média da organização
• Comparação de Latência — Latência média vs. média da organização
• Ranking do Projeto — Ranking percentil entre todos os projetos da organização
• Custo por Ambiente — Detalhamento empilhado de gastos por ambiente, com barras de progresso contra tetos de custo

No modo “Todos os Projetos”, uma tabela de breakdown mostra métricas por projeto lado a lado.

Cargo de Gerente

O cargo de gerente na organização fica entre administrador e membro. Gerentes podem:

• Criar novos projetos (até o limite do plano)
• Gerenciar projetos aos quais são atribuídos

Gerentes não podem acessar configurações da organização, faturamento ou configuração de provedores. Atribua o cargo de gerente a líderes de equipe que precisam criar e gerenciar seus próprios projetos sem acesso total de administrador.

Membros do Projeto e Cargos

Cada projeto tem sua própria lista de membros com três cargos:

Donos e admins da organização têm acesso admin implícito a todos os projetos — eles não são listados na tabela de membros do projeto a menos que se juntem explicitamente.

A gestão de membros do projeto é feita pela aba Membros do projeto. Apenas donos e admins do projeto (ou donos/admins da organização) podem adicionar ou remover membros.

Orçamentos e Alertas por Projeto

Orçamentos de equipe e alertas podem ser limitados a um projeto específico. Quando um orçamento é limitado a um projeto:

• O cálculo de custo conta apenas requisições marcadas com aquele projeto
• A revogação automática por excesso só revoga chaves de API associadas àquele projeto
• O orçamento aparece com um badge de projeto na listagem de orçamentos

Da mesma forma, alertas podem ser configurados para disparar apenas quando um projeto excede um limite.

Boas Práticas

1. Um projeto por produto ou funcionalidade — “Checkout IA”, “Busca”, “Geração de Conteúdo”
2. Uma chave de API por projeto por ambiente — Permite rastreamento de custo por ambiente sem alterações de código
3. Use chaves travadas em produção — Elimina a necessidade do header e previne atribuição acidental entre projetos
4. Atribua o cargo de gerente a líderes de equipe — Permite criar projetos sem acesso de administrador da organização
5. Defina tetos de custo por ambiente cedo — Previne custos descontrolados em produção antes de impactar seu faturamento

Requisitos por Plano