Referencia de la API

Documentación para desarrolladores sobre el acceso programático a Architecto

La API de Architecto permite crear aplicaciones, integraciones y flujos de trabajo personalizados sobre la plataforma.

Autenticación

Todas las solicitudes a la API requieren autenticación mediante una clave de API:

Authorization: Bearer YOUR_API_KEY

Crear una clave de API

Vaya a Configuración → Desarrollador → Claves de API.
Haga clic en Crear nueva clave.
Introduzca un nombre y una caducidad: nunca, 30 días, 90 días o 1 año.
Seleccione los ámbitos: lectura, escritura o administración.
Copie la clave; solo se muestra una vez.

Nunca comparta públicamente su clave de API. Trátela como una contraseña.

Revocar una clave de API

Vaya a Configuración → Desarrollador → Claves de API.
Haga clic en Revocar junto a la clave.
La revocación es inmediata.

URL base

Todos los endpoints de la API están disponibles en:

https://api.architecto.dev/v1

Endpoints habituales

Autenticación

POST /auth/login          # Login and get session
POST /auth/logout         # End session
POST /auth/refresh        # Refresh access token

Arquitecturas

GET    /architectures              # List your architectures
POST   /architectures              # Create new architecture
GET    /architectures/{id}         # Get architecture details
PUT    /architectures/{id}         # Update architecture
DELETE /architectures/{id}         # Delete architecture
GET    /architectures/{id}/versions # Get version history

Análisis

POST   /architectures/{id}/analyze/cost         # Run cost analysis
POST   /architectures/{id}/analyze/scalability  # Run scalability analysis
POST   /architectures/{id}/analyze/threats      # Run threat modeling

Documentación

POST   /architectures/{id}/documents/rfc        # Generate RFC
POST   /architectures/{id}/documents/adr        # Generate ADR
POST   /architectures/{id}/documents/runbook    # Generate runbook

POST   /architectures/{id}/shares      # Create share link
GET    /shares/{token}                 # Get shared architecture
POST   /shares/{token}/comments        # Add comment to shared arch

Equipos

GET    /organizations                  # List your organizations
POST   /organizations                  # Create organization
GET    /organizations/{id}/members     # List team members
POST   /organizations/{id}/invites     # Invite team member

Gestión de errores

Los errores de la API devuelven códigos de estado HTTP estándar:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Architecture with id 'arch_123' not found",
    "details": {
      "resource_type": "architecture",
      "resource_id": "arch_123"
    }
  }
}

Códigos de estado habituales

Código	Significado
200	Correcto
400	Solicitud incorrecta: parámetros no válidos
401	Sin autenticar: clave de API no válida
403	Prohibido: permisos insuficientes
404	No encontrado
429	Límite de solicitudes alcanzado
500	Error del servidor

Límites de solicitudes

Las solicitudes a la API tienen estos límites:

Plan Free: 100 solicitudes por hora.
Plan Pro: 1,000 solicitudes por hora.
Plan Ultimate: 10,000 solicitudes por hora.

La información sobre los límites aparece en las cabeceras de respuesta:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Ejemplo: crear y analizar una arquitectura

# 1. Create architecture
curl -X POST https://api.architecto.dev/v1/architectures \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "E-commerce Platform",
    "description": "Multi-region e-commerce with real-time inventory",
    "cloud_provider": "aws"
  }'

# Response:
# {
#   "id": "arch_abc123",
#   "title": "E-commerce Platform",
#   "created_at": "2024-01-15T10:30:00Z"
# }

# 2. Run cost analysis
curl -X POST https://api.architecto.dev/v1/architectures/arch_abc123/analyze/cost \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scale_points": [1000, 10000, 100000],
    "region": "us-east-1"
  }'

# Response:
# {
#   "analysis_id": "analysis_xyz789",
#   "estimates": [
#     {
#       "users": 1000,
#       "monthly_cost": 150,
#       "breakdown": { "compute": 80, "storage": 40, "data_transfer": 30 }
#     },
#     ...
#   ]
# }

Webhooks: próximamente

Suscríbase a eventos de arquitectura:

POST /webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["architecture.created", "architecture.updated", "analysis.completed"]
}

SDK

Próximamente habrá SDK oficiales para:

Python
Node.js / TypeScript
Go
Ruby
Java

Documentación interactiva de la API

Pruebe la API sin escribir código:

Soporte

Problemas con la API: publíquelos en GitHub Issues.
Preguntas: consulte en el Discord de la comunidad.
Empresas: contacte con sales@architecto.dev.

Siguientes pasos:

Guía de integraciones
Configuración de webhooks (próximamente)

Referencia de la API

En esta página