Instâncias do Projeto

Use estes endpoints para descobrir quais instâncias estão ativas e alterar a quantidade de réplicas de um projeto. Eles são úteis para automações de escala, rotinas de economia e painéis internos de operação.

Permissões necessárias

A listagem exige project.read em project:<project-id>. A alteração exige project.instances.update no mesmo projeto. owner tem acesso completo; assistant, member e API Keys precisam do grant da ação.

Headers

Header	Obrigatório	Descrição
`x-api-key` ou `Authorization`	Sim	API Key da organização ou token de usuário
`x-organization-id`	Com token de usuário	Organização ativa do projeto. Dispensável com API Key da organização
`Content-Type: application/json`	Sim	Necessário apenas no `PATCH`

Listar Instâncias

Retorna os identificadores das instâncias atuais do projeto.

GET /v1/project/:id/instances

Limite de requisições: 50 por minuto (contado por IP de origem).

Parâmetros de Path

Parâmetro	Tipo	Descrição
`id`	string	ID do projeto

Resposta

{
  "status": "success",
  "message": "get instances with success",
  "data": [
    { "instance": "abc" },
    { "instance": "def" }
  ]
}

Em projetos Key-Value, Cache e Queue, as instâncias aparecem como instance-1, instance-2 e assim por diante, com um campo status. Jobs agendados não têm instâncias permanentes e respondem 409.

Use o valor de instance em chamadas de métricas e logs quando quiser consultar uma instância específica.

Alterar Quantidade de Instâncias

Altera a quantidade de réplicas do projeto.

PATCH /v1/project/:id/instances

Limite de requisições: 15 por minuto (contado por IP de origem).

Body

Campo	Tipo	Obrigatório	Descrição
`instances`	number	Sim	Nova quantidade de instâncias. Deve ser um inteiro positivo.

Exemplo

{
  "instances": 3
}

Resposta

{
  "status": "success",
  "message": "project instances changed with success"
}

Regras de Operação

Situação	Resultado
`instances` igual ao valor atual	Retorna `200` com corpo de texto `OK`, sem alteração
`instances` igual a `0`	Rejeitado com `400` (validação). Use Ciclo de Vida para parar o projeto
Projeto parado	Rejeitado com `409`. Use `/resume` antes de escalar
Auto-scaling HTTP ativo	Rejeitado com `409`. Desative Auto-scaling HTTP antes de alterar manualmente
Plano mensal ou anual	Rejeitado com `409`: a escala manual só está disponível em cobrança por hora
Plano `db-free`	Não permite alteração dinâmica de instâncias (`409`)
Valkey	Rejeitado com `409`: a capacidade é definida pelo plano escolhido
Job agendado	Rejeitado com `409`
Plano Free	Limite de 2 instâncias no total; acima disso, `409`
Capacidade indisponível	`409` (capacidade solicitada indisponível) ou `503` (capacidade temporariamente indisponível); tente novamente em instantes
MariaDB	Exige exatamente 3 instâncias

Exemplos

curl

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/instances" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id"

curl -X PATCH "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/instances" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id" \
  -H "Content-Type: application/json" \
  -d '{"instances": 3}'

Python

import requests

API_KEY = "sua-api-key"
ORGANIZATION_ID = "sua-organization-id"
PROJECT_ID = "507f1f77bcf86cd799439011"

headers = {"x-api-key": API_KEY, "x-organization-id": ORGANIZATION_ID}

instances = requests.get(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/instances",
    headers=headers
).json()

scale = requests.patch(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/instances",
    headers=headers,
    json={"instances": 3}
).json()

Erros Comuns

Código	Motivo provável	Como resolver
`400`	`instances` ausente, inválido ou igual a `0`; MariaDB com quantidade diferente de 3	Envie um inteiro positivo e use `/stop` para parar
`404`	Projeto não encontrado	Verifique `Project ID`, API Key e organização
`409`	Estado, plano, cobrança, tipo de projeto, capacidade ou auto-scaling ativo não permite escala manual	Confira se o projeto está rodando e se o auto-scaling está desativado
`503`	Capacidade temporariamente indisponível	Tente novamente em instantes
`500`	Falha operacional ao aplicar escala	Tente novamente ou acione o suporte

Próximos Passos

Consulte Métricas e Logs para validar a nova instância.
Use Auto-scaling HTTP quando a aplicação precisa absorver picos automaticamente.
Use Ciclo de Vida para parar ou retomar um projeto.
Veja Armazenamento antes de aumentar instâncias com volumes persistentes.

Nessa página