# Endpoints

Documentação dos endpoints REST da API DeployAlly. Base URL: https://sys.deployally.com/api/v1.

Todos os endpoints requerem autenticação via header Authorization: Bearer da_xxx (veja Autenticação).

# Templates

# GET /templates

Lista templates publicados no catálogo.

Query Parameters:

curl -X GET "https://sys.deployally.com/api/v1/templates" \
  -H "Authorization: Bearer da_xxx"

Response (200):

{
  "success": true,
  "data": [
    {
      "id": "tpl_memos",
      "species": "memos",
      "archetype": "application",
      "version": "0.20",
      "taxonomy": {
        "kingdom": "applications",
        "family": "productivity",
        "species": "memos"
      },
      "spec_hash": "sha256:abc123...",
      "status": "published"
    }
  ]
}

# GET /templates/featured

Lista templates em destaque.

curl -X GET "https://sys.deployally.com/api/v1/templates/featured" \
  -H "Authorization: Bearer da_xxx"

# GET /templates/upcoming

Lista templates em desenvolvimento (preview).

curl -X GET "https://sys.deployally.com/api/v1/templates/upcoming" \
  -H "Authorization: Bearer da_xxx"

# GET /templates/{species}

Retorna o template completo (spec) por species.

Cache: Cache-Control: max-age=60. Para forçar refresh, adicione query string única (?_=$(date +%s)).

curl -X GET "https://sys.deployally.com/api/v1/templates/memos" \
  -H "Authorization: Bearer da_xxx"

Response:

{
  "success": true,
  "data": {
    "id": "tpl_memos",
    "species": "memos",
    "archetype": "application",
    "version": "0.20",
    "spec": {
      "image": "neosmemo/memos:0.20",
      "inputs": { "required": [...], "optional": [...] },
      "secrets": {...},
      "routes": [...],
      "healthcheck": {...},
      "storage": [...]
    },
    "spec_hash": "sha256:abc123..."
  }
}

# Taxonomy

# GET /taxonomy/tree

Retorna a árvore taxonômica completa (kingdom → family → species).

curl -X GET "https://sys.deployally.com/api/v1/taxonomy/tree" \
  -H "Authorization: Bearer da_xxx"

# GET /taxonomy/kingdoms

Lista todos os kingdoms.

# GET /taxonomy/kingdoms/{kingdom_id}

Detalhes de um kingdom.

# GET /taxonomy/families/{family_id}

Detalhes de uma family.

# GET /taxonomy/species/{species_id}

Detalhes de uma species.

# Definitions

Definitions são templates + parâmetros + metadados de instance, salvos para deploy.

# GET /definitions

Lista definitions do usuário/servidor.

curl -X GET "https://sys.deployally.com/api/v1/definitions" \
  -H "Authorization: Bearer da_xxx"

# POST /definitions

Cria uma nova definition.

Request Body:

curl -X POST "https://sys.deployally.com/api/v1/definitions" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "species": "memos",
    "instance_uid": "memos-001",
    "server_id": "srv_123",
    "inputs": {
      "WEB_HOSTNAME": "memos.exemplo.com"
    },
    "profile": "production"
  }'

# GET /definitions/{id}

Detalhes de uma definition.

# PUT /definitions/{id}

Atualiza uma definition (cria nova revisão).

# DELETE /definitions/{id}

Arquiva uma definition (soft delete).

# POST /definitions/{id}/activate

Reativa uma definition arquivada.

# GET /definitions/{id}/revisions

Lista revisões da definition.

# POST /definitions/{id}/revisions/{number}/restore

Restaura uma revisão anterior como a ativa.

# Instances

Instances representam containers em execução.

# GET /instances

Lista instances.

curl -X GET "https://sys.deployally.com/api/v1/instances" \
  -H "Authorization: Bearer da_xxx"

# GET /instances/stats

Estatísticas agregadas de instances (rodando, falhas, etc.).

# GET /instances/{id}

Detalhes de uma instance.

# POST /instances/report

Endpoint usado pelo CLI/daemon para reportar status de containers no servidor.

# POST /instances/components/sync

Sincroniza componentes (containers individuais de templates multi-component).

# POST /instances/{id}/drift

Reporta drift (diferença entre estado declarado e estado real).

# GET /instances/{id}/deployments

Histórico de deployments da instance.

# POST /instances/{id}/release

Libera recursos da instance (parar containers, remover volumes opcional).

# Actions

Actions são operações pós-deploy declaradas no template (ex: dump-database, clear-cache, create-database).

# GET /instances/{id}/actions

Lista actions disponíveis para a instance + metadados de backup.

curl -X GET "https://sys.deployally.com/api/v1/instances/inst_abc/actions" \
  -H "Authorization: Bearer da_xxx"

Response:

{
  "success": true,
  "template_species": "mysql",
  "actions": [
    {
      "name": "Dump Database",
      "slug": "dump-database",
      "description": "Export full database dump",
      "type": "exec",
      "timeout": "300s",
      "dangerous": false,
      "params": [
        {
          "name": "databases",
          "type": "string",
          "required": false,
          "default": "--all-databases"
        }
      ]
    }
  ],
  "backup": {
    "strategy": "both",
    "volumes": [{"name": "mysql_data", "critical": true}],
    "dump_action": "dump-database",
    "schedule_hint": "daily"
  }
}

# POST /instances/{id}/actions/{slug}/execute

Dispara execução de uma action. Retorna 202 Accepted com ID da execução.

curl -X POST "https://sys.deployally.com/api/v1/instances/inst_abc/actions/create-database/execute" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{"params": {"db_name": "blog"}}'

# GET /actions/{execution_id}

Consulta o status de uma execução.

Status possíveis: pending, sent, running, completed, failed, timeout, cancelled

# PUT /actions/{execution_id}

Atualiza o status de uma execução (usado pelo daemon para reportar resultado).

# GET /instances/{id}/actions/history

Histórico de execuções de uma instance.

# Playbooks

# GET /playbooks

Lista playbook types disponíveis.

# GET /playbooks/{playbook_type}

Detalhes de um playbook type.

# Servers

# GET /servers

Lista servidores registrados.

# POST /servers/register

Registra um novo servidor.

curl -X POST "https://sys.deployally.com/api/v1/servers/register" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "servidor-prod-01",
    "environment": "production"
  }'

Importante: A api_key do servidor retornada só é exibida uma vez. Armazene-a com segurança.

# GET /servers/{id}

Detalhes de um servidor.

# PUT /servers/{id}

Atualiza um servidor.

# POST /servers/{id}/rotate-key

Rotaciona a API key do servidor.

# Server Capacity

# GET /server-capacity

Lista capacidade de todos os servidores.

# GET /server-capacity/{server_id}

Capacidade de um servidor (memória usada/livre, CPU, disco).

# PUT /server-capacity/{server_id}

Atualiza informações de capacidade (usado pelo daemon).

# Deployments

# GET /deployments

Lista histórico de deployments.

# POST /deployments/execute

Dispara um deployment.

curl -X POST "https://sys.deployally.com/api/v1/deployments/execute" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{"definition_id": "def_xyz789"}'

# GET /deployments/pending

Lista deployments pendentes de execução.

# GET /deployments/{id}

Detalhes de um deployment, incluindo logs.

# PATCH /deployments/{id}/status

Atualiza status do deployment (usado pelo daemon).

# POST /deployments/{id}/rollback

Rollback de um deployment.

# Manifests

Manifests representam a spec resolvida (após Reflang) de uma instance.

# GET /manifest

Retorna o manifest da instance solicitada (usado pelo CLI durante deploy).

# POST /deploy/report

Reporta resultado de deploy (executado pelo daemon).

# Secrets

# GET /definitions/{id}/secrets (via secrets bp)

Lista secrets associados a uma definition (sem valores).

# Vault endpoints (`/vault`)

Endpoints internos para gerenciamento de secrets criptografados.

# Match

# POST /match

Encontra templates compatíveis para resolver um needs declarado.

curl -X POST "https://sys.deployally.com/api/v1/match" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "needs": [{"class": "mysql"}]
  }'

# Tenants

# GET /tenants

Lista tenants do usuário.

# POST /tenants

Cria novo tenant.

# GET /tenants/{id}

Detalhes do tenant.

# PATCH /tenants/{id}/suspend

Suspende tenant.

# PATCH /tenants/{id}/resume

Reativa tenant suspenso.

# PATCH /tenants/{id}/active

Marca tenant como ativo.

# POST /tenants/{id}/migrate

Migra tenant entre servidores.

# DELETE /tenants/{id}

Remove tenant.

# Webhooks

# GET /webhooks/endpoints

Lista endpoints de webhook configurados.

# POST /webhooks/endpoints

Cria um novo endpoint.

curl -X POST "https://sys.deployally.com/api/v1/webhooks/endpoints" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-site.com/webhook",
    "events": ["deployment.success", "instance.unhealthy"],
    "secret": "meu_webhook_secret"
  }'

# DELETE /webhooks/endpoints/{id}

Remove endpoint.

# GET /events

Lista eventos disparados (auditoria).

Eventos disponíveis:

• deployment.started
• deployment.success
• deployment.failed
• instance.started
• instance.stopped
• instance.unhealthy
• definition.created
• definition.updated
• action.completed
• action.failed

# Recipes

Recipes são templates colaborativos da comunidade (sem ser parte do catálogo curado).

# GET /recipes

Lista recipes públicas.

# GET /recipes/by-slug/{slug}

Detalhes de uma recipe por slug.

# GET /recipes/mine

Lista recipes do usuário.

# POST /recipes

Submete nova recipe para revisão.

# PATCH /recipes/{id}

Atualiza recipe.

# POST /recipes/{id}/upvote

Vota em uma recipe.

# PATCH /recipes/{id}/withdraw

Retira recipe submetida.

# DELETE /recipes/{id}

Remove recipe.

# GET /recipes/pending

Lista recipes pendentes de revisão (admin).

# POST /recipes/{id}/approve

Aprova recipe (admin).

# POST /recipes/{id}/reject

Rejeita recipe (admin).

# Saved Configs

# GET /saved-configs

Lista configurações salvas do usuário.

# POST /saved-configs

Cria nova config salva.

# GET /saved-configs/{id}

Detalhes da config.

# PATCH /saved-configs/{id}

Atualiza config.

# DELETE /saved-configs/{id}

Remove config.

# Upgrades

# GET /upgrades

Lista upgrades disponíveis para instances ativas.

# POST /upgrades/scan

Dispara scan de novas versões.

# POST /upgrades/{id}/ack

Marca upgrade como ciente (sem aplicar).

# POST /upgrades/{id}/apply

Aplica o upgrade.

# Copilot

# POST /copilot/ask

Pergunta ao Copilot (LLM com contexto do catálogo).

# GET /copilot/usage

Consumo do Copilot do usuário.

# User

# GET /user/servers

Lista servidores do usuário autenticado.

# Implant

Endpoints para download do agente Implant (servidor prep).

# GET /implant/{os_type}/{arch}

Retorna metadados do binário Implant.

# GET /implant/{os_type}/{arch}/download

Download do binário Implant.

# Health Check

# GET /health

Verifica se a API está funcionando (não requer autenticação).

curl -X GET "https://sys.deployally.com/api/v1/health"

Response:

{
  "status": "healthy",
  "timestamp": "2026-06-05T12:00:00Z"
}

# WebSocket

# WS /ws/server

Endpoint WebSocket para conexão persistente do daemon (recebe ações remotas).

Protocolo:

# Respostas Padrão

# Sucesso

{ "success": true, "data": { ... } }

# Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'name' é obrigatório"
  }
}

# Códigos de Erro

# Rate Limits

Headers de resposta:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1699900000

# Próximos Passos

• Autenticação — gerenciamento de API keys
• Integração com API — guia prático
• Referência CLI — uso programático via CLI