API Reference - Documentação Brasa

Autenticação

Todas as requisições à API devem incluir um token Bearer no header Authorization. Você pode obter seu token na página de configurações da sua conta ou via CLI com brasa login.

Authorization: Bearer seu_token_aqui

Todas as respostas são em formato JSON. Erros retornam um objeto com a chave error.

{
  "error": "Não autorizado. Verifique seu token de acesso."
}

Apps

GET /api/v1/apps

Lista todas as aplicacoes do time atual.

Exemplo de requisicao

curl -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps

Resposta (200 OK)

[
  {
    "id": 1,
    "name": "meu-saas",
    "slug": "meu-saas",
    "stack": "ruby",
    "status": "running",
    "region": "br-south-1",
    "url": "https://meu-saas.usebrasa.com.br",
    "created_at": "2025-01-10T14:30:00Z"
  }
]

GET /api/v1/apps/:slug

Retorna detalhes de uma aplicação específica, incluindo deploys recentes.

Exemplo de requisicao

curl -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps/meu-saas

Resposta (200 OK)

{
  "id": 1,
  "name": "meu-saas",
  "slug": "meu-saas",
  "stack": "ruby",
  "status": "running",
  "region": "br-south-1",
  "url": "https://meu-saas.usebrasa.com.br",
  "github_repo": "usuario/meu-saas",
  "last_deploy": {
    "id": 42,
    "status": "live",
    "commit_sha": "abc1234",
    "created_at": "2025-01-15T10:00:00Z"
  },
  "created_at": "2025-01-10T14:30:00Z"
}

POST /api/v1/apps

Cria uma nova aplicação.

Parametros

Campo	Tipo	Descrição
`name`	string	Nome da aplicação (obrigatório)
`stack`	string	Stack: `ruby`, `nodejs`, `docker`
`region`	string	Região (padrão: `br-south-1`)

Exemplo de requisicao

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app": {"name": "novo-app", "stack": "ruby"}}' \
  https://usebrasa.com.br/api/v1/apps

Resposta (201 Created)

{
  "id": 2,
  "name": "novo-app",
  "slug": "novo-app",
  "stack": "ruby",
  "status": "created",
  "region": "br-south-1",
  "url": "https://novo-app.usebrasa.com.br",
  "created_at": "2025-01-16T09:00:00Z"
}

DELETE /api/v1/apps/:slug

Remove permanentemente uma aplicação e todos os seus recursos associados.

Exemplo de requisicao

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps/novo-app

Resposta (200 OK)

{
  "message": "App removido com sucesso"
}

Deploys

POST /api/v1/apps/:slug/deploys

Inicia um novo deploy para a aplicação. O deploy é processado de forma assíncrona.

Parametros

Campo	Tipo	Descrição
`version`	string	Commit SHA ou tag para deploy

Exemplo de requisicao

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deploy": {"version": "abc1234"}}' \
  https://usebrasa.com.br/api/v1/apps/meu-saas/deploys

Resposta (201 Created)

{
  "id": 43,
  "app_slug": "meu-saas",
  "status": "building",
  "version": "abc1234",
  "created_at": "2025-01-16T09:15:00Z"
}

Variáveis de Ambiente

GET /api/v1/apps/:slug/env

Lista todas as variáveis de ambiente da aplicação.

Exemplo de requisicao

curl -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps/meu-saas/env

Resposta (200 OK)

[
  {
    "id": 1,
    "key": "DATABASE_URL",
    "value": "postgres://user:****@host/db",
    "created_at": "2025-01-10T14:30:00Z"
  },
  {
    "id": 2,
    "key": "RAILS_ENV",
    "value": "production",
    "created_at": "2025-01-10T14:30:00Z"
  }
]

PUT /api/v1/apps/:slug/env

Cria ou atualiza variáveis de ambiente em lote (bulk upsert).

Parametros

Campo	Tipo	Descrição
`env`	object	Objeto com pares chave/valor das variáveis (obrigatório)

Exemplo de requisicao

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"env": {"REDIS_URL": "redis://localhost:6379", "RAILS_ENV": "production"}}' \
  https://usebrasa.com.br/api/v1/apps/meu-saas/env

Resposta (200 OK)

{
  "message": "Variáveis de ambiente atualizadas"
}

DELETE /api/v1/apps/:slug/env/:keys

Remove variáveis de ambiente da aplicação pelo nome da chave. Aceita múltiplas chaves separadas por vírgula.

Exemplo de requisicao

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps/meu-saas/env/REDIS_URL,RAILS_ENV

Resposta (200 OK)

{
  "message": "Variáveis de ambiente removidas"
}

Domínios

GET /api/v1/apps/:slug/domains

Lista todos os domínios configurados para a aplicação.

Exemplo de requisicao

curl -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps/meu-saas/domains

Resposta (200 OK)

[
  {
    "id": 1,
    "hostname": "app.meusite.com.br",
    "verified": true,
    "ssl": true,
    "created_at": "2025-01-12T08:00:00Z"
  }
]

POST /api/v1/apps/:slug/domains

Adiciona um domínio personalizado à aplicação.

Parametros

Campo	Tipo	Descrição
`hostname`	string	Nome do domínio (obrigatório)

Exemplo de requisicao

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": {"hostname": "api.meusite.com.br"}}' \
  https://usebrasa.com.br/api/v1/apps/meu-saas/domains

Resposta (201 Created)

{
  "id": 2,
  "hostname": "api.meusite.com.br",
  "verified": false,
  "ssl": false,
  "cname_target": "meu-saas.usebrasa.com.br",
  "created_at": "2025-01-16T10:00:00Z"
}

DELETE /api/v1/apps/:slug/domains/:id

Remove um domínio personalizado da aplicação.

Exemplo de requisicao

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps/meu-saas/domains/2

Resposta (200 OK)

{
  "message": "Domínio removido com sucesso"
}

POST /api/v1/apps/:slug/domains/:id/verify

Verifica a configuração DNS de um domínio personalizado. Necessário após adicionar o registro CNAME.

Exemplo de requisicao

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://usebrasa.com.br/api/v1/apps/meu-saas/domains/2/verify

Resposta (200 OK)

{
  "id": 2,
  "hostname": "api.meusite.com.br",
  "verified": true,
  "ssl": true,
  "created_at": "2025-01-16T10:00:00Z"
}

Logs

GET /api/v1/apps/:slug/logs

Lista logs da aplicação. Use o parâmetro tail para definir o número de linhas (1-1000).

POST /api/v1/apps/:slug/logs/ingest

Ingestão de logs via Vector.dev. Autenticação via header X-Vector-Token.

GET /api/v1/apps/:slug/logs/search

Busca full-text nos logs. Parametros: query, level, source, since, until.

GET /api/v1/apps/:slug/logs/export

Exporta logs em JSON ou CSV. Use o parâmetro export_format para escolher o formato.

Database

GET /api/v1/apps/:slug/database

Retorna informações do banco de dados da aplicação.

POST /api/v1/apps/:slug/database/backups

Cria um backup (snapshot) do banco de dados.

POST /api/v1/apps/:slug/database/backups/:backup_id/restore

Restaura o banco de dados a partir de um backup existente.

Scaling

POST /api/v1/apps/:slug/scale/estimate

Retorna uma estimativa de custo para o escalonamento. Parametros: preset, web.

PUT /api/v1/apps/:slug/scale

Aplica escalonamento na aplicação. Parâmetro: preset.

Processes

GET /api/v1/apps/:slug/processes

Lista todos os processos da aplicação.

POST /api/v1/apps/:slug/processes

Cria um novo processo. Parametros: name, process_type, command, instances, schedule.

DELETE /api/v1/apps/:slug/processes/:id

Remove um processo da aplicação.

Addons

GET /api/v1/marketplace/addons

Lista todos os addons disponíveis no marketplace.

GET /api/v1/apps/:slug/addons

Lista todos os addons instalados na aplicação.

POST /api/v1/apps/:slug/addons

Instala um addon na aplicação. Parâmetros: slug, plan.

DELETE /api/v1/apps/:slug/addons/:id

Remove um addon da aplicação.

Billing

GET /api/v1/billing/usage

Retorna o usage (consumo) do mês atual.

GET /api/v1/billing/invoices

Lista todas as faturas do time.

PUT /api/v1/billing/plan

Altera o plano da assinatura. Parametro: plan.

Webhooks

POST /api/v1/github/webhooks

Recebe webhooks do GitHub para deploy automático. Configurado automaticamente quando você conecta um repositório GitHub ao seu app. Dispara um deploy quando um push é feito na branch configurada.

Nota: Este endpoint é chamado diretamente pelo GitHub. Não é necessário chamar manualmente.

POST /api/v1/webhooks/pagarme

Recebe notificações de pagamento do Pagar.me. Utilizado para processar eventos de cobrança como pagamento confirmado, falhado, reembolso, etc.

Nota: Este endpoint é chamado diretamente pelo Pagar.me. Não é necessário chamar manualmente.

Codigos de Status HTTP

Código	Descrição
`200`	Requisicao bem-sucedida
`201`	Recurso criado com sucesso
`401`	Não autorizado - token inválido ou ausente
`403`	Proibido - sem permissao para este recurso
`404`	Recurso não encontrado
`409`	Conflito - recurso ja existe ou operacao em andamento
`422`	Entidade não processável - dados inválidos
`429`	Rate limit excedido - aguarde antes de tentar novamente
`500`	Erro interno do servidor

Rate Limiting

A API possui limites de requisições para garantir a estabilidade do serviço:

100 requisições/min por IP
300 requisições/min por token

Ao exceder o limite, a API retorna status 429 com a seguinte resposta:

{
  "error": "Rate limit exceeded. Retry later."
}