API Reference - Documentacao Brasa

Autenticacao

Todas as requisicoes a API devem incluir um token Bearer no header Authorization. Voce pode obter seu token na pagina de configuracoes da sua conta ou via CLI com brasa login.

Authorization: Bearer seu_token_aqui

Todas as respostas sao em formato JSON. Erros retornam um objeto com a chave error.

{
  "error": "Nao 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 aplicacao especifica, 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 aplicacao.

Parametros

Campo	Tipo	Descricao
`name`	string	Nome da aplicacao (obrigatorio)
`stack`	string	Stack: `ruby`, `nodejs`, `docker`
`region`	string	Regiao (padrao: `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 aplicacao 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 aplicacao. O deploy e processado de forma assincrona.

Parametros

Campo	Tipo	Descricao
`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"
}

Variaveis de Ambiente

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

Lista todas as variaveis de ambiente da aplicacao.

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 variaveis de ambiente em lote (bulk upsert).

Parametros

Campo	Tipo	Descricao
`env`	object	Objeto com pares chave/valor das variaveis (obrigatorio)

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": "Variaveis de ambiente atualizadas"
}

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

Remove variaveis de ambiente da aplicacao pelo nome da chave. Aceita multiplas chaves separadas por virgula.

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": "Variaveis de ambiente removidas"
}

Dominios

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

Lista todos os dominios configurados para a aplicacao.

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 dominio personalizado a aplicacao.

Parametros

Campo	Tipo	Descricao
`hostname`	string	Nome do dominio (obrigatorio)

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 dominio personalizado da aplicacao.

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": "Dominio removido com sucesso"
}

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

Verifica a configuracao DNS de um dominio personalizado. Necessario apos 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 aplicacao. Use o parametro tail para definir o numero de linhas (1-1000).

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

Ingestao de logs via Vector.dev. Autenticacao 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 parametro export_format para escolher o formato.

Database

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

Retorna informacoes do banco de dados da aplicacao.

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 aplicacao. Parametro: preset.

Processes

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

Lista todos os processos da aplicacao.

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 aplicacao.

Addons

GET /api/v1/marketplace/addons

Lista todos os addons disponiveis no marketplace.

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

Lista todos os addons instalados na aplicacao.

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

Instala um addon na aplicacao. Parametros: slug, plan.

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

Remove um addon da aplicacao.

Billing

GET /api/v1/billing/usage

Retorna o usage (consumo) do mes 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 automatico. Configurado automaticamente quando voce conecta um repositorio GitHub ao seu app. Dispara um deploy quando um push e feito na branch configurada.

Nota: Este endpoint e chamado diretamente pelo GitHub. Nao e necessario chamar manualmente.

POST /api/v1/webhooks/pagarme

Recebe notificacoes de pagamento do Pagar.me. Utilizado para processar eventos de cobranca como pagamento confirmado, falhado, reembolso, etc.

Nota: Este endpoint e chamado diretamente pelo Pagar.me. Nao e necessario chamar manualmente.

Codigos de Status HTTP

Codigo	Descricao
`200`	Requisicao bem-sucedida
`201`	Recurso criado com sucesso
`401`	Nao autorizado - token invalido ou ausente
`403`	Proibido - sem permissao para este recurso
`404`	Recurso nao encontrado
`409`	Conflito - recurso ja existe ou operacao em andamento
`422`	Entidade nao processavel - dados invalidos
`429`	Rate limit excedido - aguarde antes de tentar novamente
`500`	Erro interno do servidor

Rate Limiting

A API possui limites de requisicoes para garantir a estabilidade do servico:

100 requisicoes/min por IP
300 requisicoes/min por token

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

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