API Zenifra

A API da Zenifra permite gerenciar projetos de forma programática: consultar status, alterar configurações, escalar instâncias, obter logs e acompanhar métricas de rede.

Antes de começar

Você precisa de três identificadores antes de chamar os endpoints de projeto:

Valor	Onde usar	Descrição
API Key	Header `x-api-key`	Chave do projeto usada para autenticar a chamada
Organization ID	Header `x-organization-id`	Organização ativa onde o projeto existe
Project ID	Path `:id`	ID do projeto usado na URL

x-organization-id faz parte do contrato público da API. Em chamadas com x-api-key, a API consegue identificar o projeto pela chave; em chamadas com Authorization: Bearer, o header define a organização ativa e evita falhas de permissão.

Use x-api-key em todos os endpoints desta seção. Inclua também x-organization-id para manter o contexto correto da organização, principalmente em contas com múltiplas organizações ou automações compartilhadas.

Headers

Header	Obrigatório	Quando usar	Descrição
`x-api-key`	Sim	Todas as chamadas de projeto	API Key do projeto
`x-organization-id`	Sim	Todas as chamadas documentadas	Organização ativa do projeto
`Content-Type: application/json`	Sim	Requisições com body	Indica que o payload está em JSON

URL Base

Todas as requisições devem ser feitas para:

https://api.zenifra.com/v1

Exemplo de Requisição

curl -X GET "https://api.zenifra.com/v1/project/{id}/metrics" \
  -H "x-api-key: sua-api-key-aqui" \
  -H "x-organization-id: sua-organization-id"

Endpoints por tarefa

Use esta visão para escolher rapidamente qual página abrir:

Tarefa	Página	Endpoints principais
Consultar o projeto	Informações do Projeto	`GET /project/:id`, `PATCH /name`, `PATCH /description`
Fazer deploy por imagem	Atualizar Imagem de Deploy	`PATCH /project/:id/image`
Configurar variáveis	Variáveis de Ambiente	`GET /envs`, `PATCH /envs`
Alterar domínio	Domínio	`PATCH /domain`
Parar ou retomar	Ciclo de Vida	`PATCH /stop`, `PATCH /resume`
Escalar instâncias	Instâncias	`GET /instances`, `PATCH /instances`
Ver deploys anteriores	Deployments	`GET /historic/deployments`
Observar métricas e logs	Métricas e Logs	`GET /metrics`, `GET /logs`
Investigar tráfego HTTP	Métricas de Rede	`GET /metrics/network/*`
Alterar plano	Plano	`PATCH /plan`
Gerenciar armazenamento	Armazenamento	`PATCH /storage/size`, `GET /storage/usage`

Códigos de Status HTTP

Código	Descrição
`200`	Requisição bem sucedida
`400`	Dados inválidos ou mal formatados
`401`	API Key inválida ou não fornecida
`402`	Plano não permite o recurso solicitado
`403`	Organização ou permissão insuficiente
`404`	Projeto não encontrado
`409`	Operação não permitida no estado atual do projeto
`500`	Erro interno do servidor

Exemplos de Uso

Python

import requests

API_KEY = "sua-api-key"
ORGANIZATION_ID = "sua-organization-id"
BASE_URL = "https://api.zenifra.com/v1"

headers = {
    "x-api-key": API_KEY,
    "x-organization-id": ORGANIZATION_ID,
    "Content-Type": "application/json"
}

# Obter métricas do projeto
response = requests.get(
    f"{BASE_URL}/project/507f1f77bcf86cd799439011/metrics",
    headers=headers
)
print(response.json())

Node.js

const axios = require('axios');

const API_KEY = 'sua-api-key';
const ORGANIZATION_ID = 'sua-organization-id';
const BASE_URL = 'https://api.zenifra.com/v1';

const headers = {
  'x-api-key': API_KEY,
  'x-organization-id': ORGANIZATION_ID,
  'Content-Type': 'application/json'
};

async function getMetrics(projectId) {
  const response = await axios.get(
    `${BASE_URL}/project/${projectId}/metrics`,
    { headers }
  );
  return response.data;
}

getMetrics('507f1f77bcf86cd799439011')
  .then(console.log)
  .catch(console.error);

FAQ

Onde encontro a API Key e o Project ID do meu projeto?

Importante: Tanto a API Key quanto o Project ID são exibidos apenas uma vez, no momento da criação do projeto. Após essa tela inicial, não é mais possível acessá-los pelo console.

Por isso, guarde essas informações em local seguro imediatamente após criar seu projeto.

Posso usar a API Key para qualquer projeto?

Sim, cada projeto possui sua própria API Key. A chave garante acesso apenas ao projeto específico ao qual pertence.

O `x-organization-id` é sempre necessário?

Na prática, chamadas com x-api-key conseguem localizar o projeto pela própria chave. Ainda assim, inclua x-organization-id em todas as automações: ele deixa explícita a organização ativa, mantém compatibilidade com fluxos que usam token de usuário e reduz erros de permissão em contas com múltiplas organizações.

Os endpoints possuem rate limiting?

Sim, a API possui rate limiting para garantir estabilidade. O limite atual é de 100 requisições por minuto por projeto. Se você exceder o limite, receberá erros 429 (Too Many Requests).

Para limites maiores, entre em contato com o suporte.