Informações de projetos

Esta referência cobre a listagem paginada de projetos e a consulta ou atualização de um projeto específico.

Autenticação e permissões

Envie uma sessão autorizada ou uma API Key da organização com o contexto da organização. A listagem retorna somente os projetos que a credencial pode consultar. A consulta de um projeto exige project.read em project:<project-id>. Para as atualizações desta página, use também project.name.update, project.description.update ou project.domain.update, conforme a operação.

Listar projetos

GET /v1/project

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
`page`	inteiro	`1`	Página da listagem; deve ser maior ou igual a 1
`limit`	inteiro	`15`	Itens por página, de 1 a 50
`type`	string	—	`http`, `postgresql`, `mariadb` ou `valkey`
`profile`	string	—	Perfil Valkey: `key_value`, `cache` ou `queue`; só é aceito com `type=valkey`
`status`	string	—	`creating`, `running`, `resuming`, `stopped`, `downloading`, `failed`, `failing` ou `deploying`
`search`	string	—	Busca por nome ou descrição (1 a 256 caracteres)
`sort_by`	string	`updated_at`	`updated_at` ou `created_at`
`sort_order`	string	`desc`	`asc` ou `desc`

Os filtros podem ser combinados. Para listar somente caches Valkey, por exemplo:

curl "https://api.zenifra.com/v1/project?type=valkey&profile=cache&page=1&limit=15" \
  -H "x-api-key: <organization-api-key>" \
  -H "x-organization-id: <organization-id>"

Resposta reduzida

{
  "status": "success",
  "message": "get projects with success",
  "data": {
    "projects": [
      {
        "id": "<project-id>",
        "name": "cache-da-api",
        "type_project": "valkey",
        "plan": "cache-free",
        "status": "running",
        "managed_service": { "profile": "cache" }
      }
    ],
    "pagination": { "page": 1, "limit": 15, "total": 1, "pages": 1 }
  }
}

Limite de requisições: 100 por minuto.

A API retorna 400 quando profile não é key_value, cache ou queue, ou quando ele é enviado sem type=valkey.

Obter informações de um projeto

Retorna o estado atual do projeto, incluindo status, plano, domínio, instâncias, storage, porta, configurações públicas de deploy e informações adicionais por tipo de projeto.

GET /v1/project/:id

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

Parâmetros de Path

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

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`	Condicional	Necessário apenas nas chamadas `PATCH`

Resposta

O exemplo abaixo é reduzido para destacar os campos mais usados. A resposta também pode incluir campos como github, image, last_deployment, renew_automatic_contract, custom_domains, network_access, build_failure, updated_at e created_at.

Em projetos HTTP, exposure indica se a aplicação possui rota pública (public) ou roda sem domínio público (private). Projetos privados podem retornar domain vazio ou ausente.

{
  "status": "success",
  "message": "get deployment with success",
  "data": {
    "name": "meu-projeto",
    "description": "Minha aplicação web",
    "domain": "meu-projeto.clients.zenifra.com",
    "plan": "basic",
    "status": "running",
    "type_project": "http",
    "exposure": "public",
    "instances": 2,
    "storage": {
      "persistent": false,
      "capacity": 1
    },
    "payment_mode": "hourly",
    "port": 3000,
    "additional_info": {
      "current_instances": 2,
      "max_cpu": "500m",
      "max_memory": "512Mi"
    }
  }
}

Atualizar Exposição do Projeto

Altera se um projeto HTTP expõe rota pública.

PATCH /v1/project/:id/exposure

Aceita sessão de usuário ou API Key da organização. Exige project.domain.update.

Body

Campo	Tipo	Obrigatório	Descrição
`exposure`	string	Sim	Use `public` para criar rota/domínio público ou `private` para remover a exposição pública

{
  "exposure": "private"
}

Projetos privados não recebem subdomain da Zenifra e não aceitam configuração de domínio público enquanto permanecerem privados. Somente projetos HTTP aceitam esta operação.

Resposta

{
  "status": "success",
  "message": "project exposure updated with success",
  "exposure": "private",
  "domain": "",
  "custom_domains": []
}

Ao alterar para private, a API remove a rota pública, o subdomain padrão e domínios personalizados. Ao alterar para public, a API provisiona novamente a rota pública e retorna o domínio disponível.

Erros

Status	Quando ocorre
`400`	O projeto é um banco de dados (`cant change database exposure`)
`404`	Projeto não encontrado
`409`	Já existe uma alteração de exposição em andamento para o projeto, ou o domínio solicitado não está disponível
`503`	Não foi possível atribuir um endereço público agora; tente novamente em instantes

Limite de requisições: 5 a cada 5 minutos.

Atualizar Nome do Projeto

Altera o nome do projeto.

PATCH /v1/project/:id/name

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

Parâmetros de Path

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

Body

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Novo nome do projeto (mínimo 6 caracteres, máximo 32, apenas letras minúsculas e números, pode usar hífen)

Exemplo

{
  "name": "meu-novo-projeto"
}

Resposta

{
  "status": "success",
  "message": "updated with success"
}

Atualizar Descrição do Projeto

Altera a descrição do projeto.

PATCH /v1/project/:id/description

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

Parâmetros de Path

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

Body

Campo	Tipo	Obrigatório	Descrição
`description`	string	Não	Nova descrição do projeto (de 1 a 256 caracteres)

Resposta

{
  "status": "success",
  "message": "updated with success"
}

Exemplos

Atualizar Nome

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

Atualizar Descrição

curl -X PATCH "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/description" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id" \
  -H "Content-Type: application/json" \
  -d '{"description": "Minha aplicação web em produção"}'

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}

# Obter informações
project = requests.get(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}",
    headers=headers
).json()
print(project)

# Atualizar nome
requests.patch(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/name",
    headers=headers,
    json={"name": "meu-novo-projeto"}
)

# Atualizar descrição
requests.patch(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/description",
    headers=headers,
    json={"description": "Minha aplicação web em produção"}
)

Nessa página