Referência da API de Squads

API REST para sincronizar squads com Synkra e descobrir squads do marketplace.

Visão Geral

A API de Squads permite:

Sync: Enviar squads locais para a nuvem Synkra
Marketplace: Descobrir e navegar squads públicos
Gerenciamento: Atualizar visibilidade, excluir squads

URL Base: https://api.synkra.ai

Autenticação

Todos os endpoints autenticados requerem:

Chave de API (Recomendado para CLI)


Authorization: Bearer sk_your_api_key

Token JWT (Aplicações web)


Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Obtenha sua chave de API em: https://synkra.ai/settings/api-keys

Endpoints

Sincronizar Squad

Enviar uma definição de squad para Synkra.


POST /api/squads/sync

Autenticação: Obrigatória

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`squadData`	object	Sim	Dados do manifesto do squad
`squadData.name`	string	Sim	Nome do squad
`squadData.version`	string	Sim	Versão semântica
`squadData.description`	string	Não	Descrição do squad
`squadData.author`	string	Não	Nome do autor
`squadData.components`	object	Não	Componentes do squad
`isPublic`	boolean	Não	Tornar publicamente visível (padrão: false)
`isOfficial`	boolean	Não	Marcar como oficial (apenas admin)

Exemplo de Requisição:


curl -X POST https://api.synkra.ai/api/squads/sync \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "squadData": {
      "name": "my-squad",
      "version": "1.0.0",
      "description": "Meu squad incrível",
      "aios": {
        "minVersion": "2.1.0",
        "type": "squad"
      },
      "components": {
        "agents": ["greeter-agent"],
        "tasks": ["greet-user"]
      }
    },
    "isPublic": true
  }'

Resposta de Sucesso (200):


{
  "success": true,
  "data": {
    "squad_id": "my-squad",
    "action": "created",
    "version": "1.0.0",
    "is_public": true
  },
  "duration_ms": 45
}

Resposta de Erro (400):


{
  "success": false,
  "error": "Validation failed: name is required"
}

Sincronização em Lote

Sincronizar múltiplos squads em uma requisição.


POST /api/squads/sync/batch

Autenticação: Obrigatória

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`squads`	array	Sim	Array de objetos de dados de squad
`isPublic`	boolean	Não	Tornar todos os squads públicos (padrão: false)

Exemplo de Requisição:


curl -X POST https://api.synkra.ai/api/squads/sync/batch \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "squads": [
      {
        "name": "squad-one",
        "version": "1.0.0",
        "description": "Primeiro squad"
      },
      {
        "name": "squad-two",
        "version": "2.0.0",
        "description": "Segundo squad"
      }
    ],
    "isPublic": false
  }'

Resposta de Sucesso (200):


{
  "success": true,
  "data": {
    "total": 2,
    "created": 2,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "errors": [],
    "duration_ms": 120
  }
}

Resposta de Falha Parcial (200):


{
  "success": false,
  "data": {
    "total": 2,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "failed": 1,
    "errors": [
      {
        "index": 1,
        "squad_name": "squad-two",
        "error": "Validation failed: version is required"
      }
    ],
    "duration_ms": 85
  }
}

Listar Squads Públicos (Marketplace)

Navegar squads disponíveis no marketplace.


GET /api/squads

Autenticação: Opcional

Parâmetros de Query:

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Número da página
`limit`	number	20	Itens por página (máx: 100)
`tags`	string	-	Filtro de tags separadas por vírgula
`author`	string	-	Filtrar por autor
`search`	string	-	Buscar em nome/descrição
`official`	boolean	-	Filtrar apenas squads oficiais

Exemplo de Requisição:


# Listar todos os squads públicos
curl https://api.synkra.ai/api/squads
 
# Buscar com filtros
curl "https://api.synkra.ai/api/squads?tags=devops,automation&search=deploy&official=true&limit=10"

Resposta de Sucesso (200):


{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "squad_id": "devops-squad",
      "name": "devops-squad",
      "version": "2.1.0",
      "description": "Squad de automação DevOps",
      "author": "SynkraAI",
      "tags": ["devops", "automation", "ci-cd"],
      "is_public": true,
      "is_official": true,
      "created_at": "2025-12-01T10:00:00Z",
      "updated_at": "2025-12-15T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasMore": true
  }
}

Listar Meus Squads

Listar squads pertencentes ao seu workspace.


GET /api/squads/mine

Autenticação: Obrigatória

Parâmetros de Query:

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Número da página
`limit`	number	20	Itens por página

Exemplo de Requisição:


curl https://api.synkra.ai/api/squads/mine \
  -H "Authorization: Bearer sk_your_api_key"

Resposta de Sucesso (200):


{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "squad_id": "my-private-squad",
      "name": "my-private-squad",
      "version": "1.0.0",
      "description": "Meu squad interno",
      "is_public": false,
      "is_official": false,
      "sync_status": "synced",
      "last_synced_at": "2025-12-20T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

Obter Detalhes do Squad

Obter informações detalhadas sobre um squad específico.


GET /api/squads/:id

Autenticação: Opcional (obrigatória para squads privados)

Parâmetros de Path:

Parâmetro	Tipo	Descrição
`id`	string	UUID do squad ou squad_id

Exemplo de Requisição:


# Por squad_id
curl https://api.synkra.ai/api/squads/devops-squad
 
# Por UUID
curl https://api.synkra.ai/api/squads/550e8400-e29b-41d4-a716-446655440000

Resposta de Sucesso (200):


{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "squad_id": "devops-squad",
    "name": "devops-squad",
    "version": "2.1.0",
    "description": "Squad de automação DevOps para pipelines CI/CD",
    "author": "SynkraAI",
    "license": "MIT",
    "slash_prefix": "devops",
    "tags": ["devops", "automation", "ci-cd"],
    "is_public": true,
    "is_official": true,
    "manifest": {
      "name": "devops-squad",
      "version": "2.1.0",
      "aios": {
        "minVersion": "2.1.0",
        "type": "squad"
      },
      "components": {
        "agents": ["deploy-agent", "monitor-agent"],
        "tasks": ["deploy-app", "check-health"]
      }
    },
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-15T14:30:00Z"
  }
}

Resposta de Erro (404):


{
  "success": false,
  "error": "Squad not found"
}

Atualizar Squad

Atualizar configurações de visibilidade do squad.


PATCH /api/squads/:id

Autenticação: Obrigatória (apenas proprietário)

Parâmetros de Path:

Parâmetro	Tipo	Descrição
`id`	string	UUID do squad ou squad_id

Corpo da Requisição:

Campo	Tipo	Descrição
`isPublic`	boolean	Definir visibilidade pública

Exemplo de Requisição:


curl -X PATCH https://api.synkra.ai/api/squads/my-squad \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"isPublic": true}'

Resposta de Sucesso (200):


{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "squad_id": "my-squad",
    "name": "my-squad",
    "is_public": true,
    "updated_at": "2025-12-26T10:00:00Z"
  }
}

Excluir Squad

Remover um squad do Synkra.


DELETE /api/squads/:id

Autenticação: Obrigatória (apenas proprietário)

Parâmetros de Path:

Parâmetro	Tipo	Descrição
`id`	string	UUID do squad ou squad_id

Exemplo de Requisição:


curl -X DELETE https://api.synkra.ai/api/squads/my-old-squad \
  -H "Authorization: Bearer sk_your_api_key"

Resposta de Sucesso (200):


{
  "success": true,
  "message": "Squad deleted successfully"
}

Validar Squad

Validar dados do squad sem persistir.


POST /api/squads/validate

Autenticação: Opcional

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`squadData`	object	Sim	Manifesto do squad para validar

Exemplo de Requisição:


curl -X POST https://api.synkra.ai/api/squads/validate \
  -H "Content-Type: application/json" \
  -d '{
    "squadData": {
      "name": "test-squad",
      "version": "1.0.0"
    }
  }'

Resposta de Sucesso (200):


{
  "success": true,
  "data": {
    "valid": true,
    "errors": [],
    "warnings": ["Missing recommended field: description", "Missing aios.minVersion field"]
  }
}

Resposta de Falha na Validação (200):


{
  "success": false,
  "data": {
    "valid": false,
    "errors": ["name is required", "version must be valid semver"],
    "warnings": []
  }
}

Códigos de Erro

Código HTTP	Significado
200	Sucesso
400	Bad Request - Entrada inválida
401	Unauthorized - Autenticação ausente ou inválida
403	Forbidden - Permissões insuficientes
404	Not Found - Squad não existe
500	Internal Server Error

Formato de Resposta de Erro


{
  "success": false,
  "error": "Mensagem de erro legível"
}

Limites de Taxa

Plano	Requisições/min	Requisições/dia
Free	60	1.000
Pro	300	10.000
Enterprise	Ilimitado	Ilimitado

Headers de limite de taxa:


X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1703577600

Integração CLI

O comando *sync-squad-synkra usa esta API:


# Sincronizar um único squad
@squad-creator
*sync-squad-synkra ./squads/my-squad --public
 
# Sincronização em lote de todos os squads
*sync-squad-synkra ./squads/* --public

Configurar chave de API:


export SYNKRA_API_TOKEN="sk_your_api_key"

Coleção Postman

Importe esta coleção no Postman ou Insomnia:


{
  "info": {
    "name": "Synkra Squads API",
    "description": "API REST para o Marketplace de Squads Synkra",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.synkra.ai"
    },
    {
      "key": "apiKey",
      "value": "sk_your_api_key"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}"
      }
    ]
  },
  "item": [
    {
      "name": "Sync",
      "item": [
        {
          "name": "Sync Squad",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/squads/sync",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"squadData\": {\n    \"name\": \"my-squad\",\n    \"version\": \"1.0.0\",\n    \"description\": \"My squad\",\n    \"aios\": {\n      \"minVersion\": \"2.1.0\",\n      \"type\": \"squad\"\n    }\n  },\n  \"isPublic\": false\n}"
            }
          }
        },
        {
          "name": "Batch Sync",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/squads/sync/batch",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"squads\": [\n    {\"name\": \"squad-1\", \"version\": \"1.0.0\"},\n    {\"name\": \"squad-2\", \"version\": \"1.0.0\"}\n  ],\n  \"isPublic\": false\n}"
            }
          }
        }
      ]
    },
    {
      "name": "Marketplace",
      "item": [
        {
          "name": "List Public Squads",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{baseUrl}}/api/squads?page=1&limit=20",
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "20" },
                { "key": "tags", "value": "devops", "disabled": true },
                { "key": "search", "value": "", "disabled": true },
                { "key": "official", "value": "true", "disabled": true }
              ]
            }
          }
        },
        {
          "name": "Get Squad Details",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/squads/devops-squad"
          }
        }
      ]
    },
    {
      "name": "Management",
      "item": [
        {
          "name": "List My Squads",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/squads/mine"
          }
        },
        {
          "name": "Update Squad Visibility",
          "request": {
            "method": "PATCH",
            "url": "{{baseUrl}}/api/squads/my-squad",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"isPublic\": true\n}"
            }
          }
        },
        {
          "name": "Delete Squad",
          "request": {
            "method": "DELETE",
            "url": "{{baseUrl}}/api/squads/my-squad"
          }
        }
      ]
    },
    {
      "name": "Validation",
      "item": [
        {
          "name": "Validate Squad",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/squads/validate",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"squadData\": {\n    \"name\": \"test-squad\",\n    \"version\": \"1.0.0\"\n  }\n}"
            }
          }
        }
      ]
    }
  ]
}

Salve o JSON acima como synkra-squads-api.postman_collection.json e importe no Postman.

Recursos Relacionados

Versão: 1.0.0 | Atualizado: 2025-12-26 | Story: SQS-8