Skip to content

squads-api.md

Latest commit

 

History

History
753 lines (613 loc) · 16.8 KB

squads-api.md

File metadata and controls

753 lines (613 loc) · 16.8 KB
Raw

Referencia de la API de Squads

API REST para sincronizar squads con Synkra y descubrir squads del marketplace.

Vision General

La API de Squads permite:

  • Sync: Enviar squads locales a la nube de Synkra
  • Marketplace: Descubrir y explorar squads publicos
  • Gestion: Actualizar visibilidad, eliminar squads

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

Autenticacion

Todos los endpoints autenticados requieren:

Clave API (Recomendado para CLI)

Authorization: Bearer sk_tu_clave_api

Token JWT (Aplicaciones web)

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Obtiene tu clave API de: https://synkra.ai/settings/api-keys

Endpoints

Sincronizar Squad

Envia una definicion de squad a Synkra.

POST /api/squads/sync

Autenticacion: Requerida

Cuerpo de la Solicitud:

Campo Tipo Requerido Descripcion
squadData object Si Datos del manifiesto del squad
squadData.name string Si Nombre del squad
squadData.version string Si Version semantica
squadData.description string No Descripcion del squad
squadData.author string No Nombre del autor
squadData.components object No Componentes del squad
isPublic boolean No Hacer visible publicamente (predeterminado: false)
isOfficial boolean No Marcar como oficial (solo admin)

Ejemplo de Solicitud:

curl -X POST https://api.synkra.ai/api/squads/sync \
  -H "Authorization: Bearer sk_tu_clave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "squadData": {
      "name": "mi-squad",
      "version": "1.0.0",
      "description": "Mi squad increible",
      "aiox": {
        "minVersion": "2.1.0",
        "type": "squad"
      },
      "components": {
        "agents": ["greeter-agent"],
        "tasks": ["greet-user"]
      }
    },
    "isPublic": true
  }'

Respuesta Exitosa (200):

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

Respuesta de Error (400):

{
  "success": false,
  "error": "Validacion fallida: nombre es requerido"
}

Sincronizacion por Lotes

Sincroniza multiples squads en una solicitud.

POST /api/squads/sync/batch

Autenticacion: Requerida

Cuerpo de la Solicitud:

Campo Tipo Requerido Descripcion
squads array Si Array de objetos de datos de squad
isPublic boolean No Hacer todos los squads publicos (predeterminado: false)

Ejemplo de Solicitud:

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

Respuesta Exitosa (200):

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

Respuesta de Falla Parcial (200):

{
  "success": false,
  "data": {
    "total": 2,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "failed": 1,
    "errors": [
      {
        "index": 1,
        "squad_name": "squad-dos",
        "error": "Validacion fallida: version es requerida"
      }
    ],
    "duration_ms": 85
  }
}

Listar Squads Publicos (Marketplace)

Explora los squads disponibles en el marketplace.

GET /api/squads

Autenticacion: Opcional

Parametros de Consulta:

Parametro Tipo Predeterminado Descripcion
page number 1 Numero de pagina
limit number 20 Items por pagina (max: 100)
tags string - Filtro de tags separados por coma
author string - Filtrar por autor
search string - Buscar en nombre/descripcion
official boolean - Filtrar solo squads oficiales

Ejemplo de Solicitud:

# Listar todos los squads publicos
curl https://api.synkra.ai/api/squads

# Buscar con filtros
curl "https://api.synkra.ai/api/squads?tags=devops,automation&search=deploy&official=true&limit=10"

Respuesta Exitosa (200):

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "squad_id": "devops-squad",
      "name": "devops-squad",
      "version": "2.1.0",
      "description": "Squad de automatizacion 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 Mis Squads

Lista squads propiedad de tu workspace.

GET /api/squads/mine

Autenticacion: Requerida

Parametros de Consulta:

Parametro Tipo Predeterminado Descripcion
page number 1 Numero de pagina
limit number 20 Items por pagina

Ejemplo de Solicitud:

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

Respuesta Exitosa (200):

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "squad_id": "mi-squad-privado",
      "name": "mi-squad-privado",
      "version": "1.0.0",
      "description": "Mi 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
  }
}

Obtener Detalles del Squad

Obtiene informacion detallada sobre un squad especifico.

GET /api/squads/:id

Autenticacion: Opcional (requerida para squads privados)

Parametros de Ruta:

Parametro Tipo Descripcion
id string UUID del squad o squad_id

Ejemplo de Solicitud:

# 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

Respuesta Exitosa (200):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "squad_id": "devops-squad",
    "name": "devops-squad",
    "version": "2.1.0",
    "description": "Squad de automatizacion 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",
      "aiox": {
        "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"
  }
}

Respuesta de Error (404):

{
  "success": false,
  "error": "Squad no encontrado"
}

Actualizar Squad

Actualiza la configuracion de visibilidad del squad.

PATCH /api/squads/:id

Autenticacion: Requerida (solo propietario)

Parametros de Ruta:

Parametro Tipo Descripcion
id string UUID del squad o squad_id

Cuerpo de la Solicitud:

Campo Tipo Descripcion
isPublic boolean Establecer visibilidad publica

Ejemplo de Solicitud:

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

Respuesta Exitosa (200):

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

Eliminar Squad

Elimina un squad de Synkra.

DELETE /api/squads/:id

Autenticacion: Requerida (solo propietario)

Parametros de Ruta:

Parametro Tipo Descripcion
id string UUID del squad o squad_id

Ejemplo de Solicitud:

curl -X DELETE https://api.synkra.ai/api/squads/mi-squad-antiguo \
  -H "Authorization: Bearer sk_tu_clave_api"

Respuesta Exitosa (200):

{
  "success": true,
  "message": "Squad eliminado exitosamente"
}

Validar Squad

Valida datos del squad sin persistir.

POST /api/squads/validate

Autenticacion: Opcional

Cuerpo de la Solicitud:

Campo Tipo Requerido Descripcion
squadData object Si Manifiesto del squad a validar

Ejemplo de Solicitud:

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

Respuesta Exitosa (200):

{
  "success": true,
  "data": {
    "valid": true,
    "errors": [],
    "warnings": ["Falta campo recomendado: description", "Falta campo aiox.minVersion"]
  }
}

Respuesta de Falla de Validacion (200):

{
  "success": false,
  "data": {
    "valid": false,
    "errors": ["nombre es requerido", "version debe ser semver valido"],
    "warnings": []
  }
}

Codigos de Error

Codigo HTTP Significado
200 Exito
400 Solicitud Incorrecta - Entrada invalida
401 No Autorizado - Autenticacion faltante o invalida
403 Prohibido - Permisos insuficientes
404 No Encontrado - El squad no existe
500 Error Interno del Servidor

Formato de Respuesta de Error

{
  "success": false,
  "error": "Mensaje de error legible"
}

Limites de Tasa

Plan Solicitudes/min Solicitudes/dia
Gratis 60 1,000
Pro 300 10,000
Enterprise Ilimitado Ilimitado

Headers de limite de tasa:

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

Integracion CLI

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

# Sincronizar squad individual
@squad-creator
*sync-squad-synkra ./squads/mi-squad --public

# Sincronizacion por lotes de todos los squads
*sync-squad-synkra ./squads/* --public

Configurar clave API:

export SYNKRA_API_TOKEN="sk_tu_clave_api"

Coleccion Postman

Importa esta coleccion en Postman o Insomnia:

{
  "info": {
    "name": "API de Squads Synkra",
    "description": "API REST para el Marketplace de Squads de 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_tu_clave_api"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}"
      }
    ]
  },
  "item": [
    {
      "name": "Sync",
      "item": [
        {
          "name": "Sincronizar Squad",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/squads/sync",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"squadData\": {\n    \"name\": \"mi-squad\",\n    \"version\": \"1.0.0\",\n    \"description\": \"Mi squad\",\n    \"aiox\": {\n      \"minVersion\": \"2.1.0\",\n      \"type\": \"squad\"\n    }\n  },\n  \"isPublic\": false\n}"
            }
          }
        },
        {
          "name": "Sincronizacion por Lotes",
          "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": "Listar Squads Publicos",
          "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": "Obtener Detalles del Squad",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/squads/devops-squad"
          }
        }
      ]
    },
    {
      "name": "Gestion",
      "item": [
        {
          "name": "Listar Mis Squads",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/squads/mine"
          }
        },
        {
          "name": "Actualizar Visibilidad del Squad",
          "request": {
            "method": "PATCH",
            "url": "{{baseUrl}}/api/squads/mi-squad",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"isPublic\": true\n}"
            }
          }
        },
        {
          "name": "Eliminar Squad",
          "request": {
            "method": "DELETE",
            "url": "{{baseUrl}}/api/squads/mi-squad"
          }
        }
      ]
    },
    {
      "name": "Validacion",
      "item": [
        {
          "name": "Validar 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}"
            }
          }
        }
      ]
    }
  ]
}

Guarda el JSON anterior como synkra-squads-api.postman_collection.json e importa en Postman.

Recursos Relacionados

Version: 1.0.0 | Actualizado: 2025-12-26 | Story: SQS-8