Descripción general de la API REST

¿Qué es esto?

La API REST de ComStack es la interfaz HTTP sobre la que se construye el servidor MCP. Cubre la gestión de páginas, publicación, sesiones de voz en vivo, configuración de proyectos, autenticación y plantillas.

URL base: https://api.comstack.ai

El servidor MCP envuelve estas mismas operaciones. Si utilizas Claude, Cursor u otro cliente MCP, no necesitas llamar a la API REST directamente. Úsala al integrar desde un servidor personalizado, webhook o pipeline de CI.

Cómo funciona

Autenticación

Dos métodos:

Token OAuth Bearer — para cuentas de usuario. Se obtiene mediante el flujo OAuth; envíalo como Authorization: Bearer <token>. Consulta la referencia de autenticación.
Clave de API de servicio — para llamadas headless. Configura los encabezados x-project-id y x-api-key. Genera las claves en la configuración del proyecto.

Formato de respuesta

Las respuestas exitosas devuelven JSON. Los errores devuelven { "error": "..." }:

Estado	Significado
`400`	Solicitud no válida: argumentos faltantes o mal formados
`401`	Autenticación requerida
`403`	Rol insuficiente, módulo deshabilitado o prueba expirada
`404`	Recurso no encontrado
`413`	Carga útil demasiado grande (1 MB general; 10 MB para carga de imágenes)
`429`	Límite de tasa excedido
`500`	Error interno

Límites de tasa

Por IP, ventana deslizante de 60 segundos:

Endpoint	Límite
`POST /mcp`	60 solicitudes/min
`/oauth/*`	30 solicitudes/min
Fallos de autenticación (respuestas 401)	10/min antes de activar el 429

Grupos de endpoints

OAuth y autenticación

/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize, /oauth/token

Proyectos

GET/POST /api/projects, GET/PATCH/DELETE /api/projects/:id, miembros, dominios, módulos, configuración

Páginas (conocimiento)

Crear, editar (/docs/edit/open, /edit/save, /edit/discard), listar, flujo de publicación, visibilidad

Páginas personalizadas

POST /api/projects/:id/docs/edit/upload-custom-page — para cuerpos de página personalizados en HTML/Astro

Publicación

POST /api/projects/:id/publish, POST .../publish/confirm, GET .../publish/history

La publicación es un flujo de dos pasos: la prueba (dry-run) genera un manifiesto + token de confirmación; la confirmación promueve y despliega. Consulta la referencia de publicación.

Voz en vivo

POST /api/live/session, /session/resume, /tools/execute, /twilio/voice

Barra lateral y navegación

/api/projects/:id/sidebar-groups, /api/projects/:id/header-nav-items

Plantillas

/api/templates/doc, /api/templates/project, /api/projects/:id/templates

Ingesta (Extensión de Chrome)

/api/projects/:id/ingest/* — capturar, extraer y guardar páginas desde la extensión de Chrome

Claves de API

/api/projects/:id/keys

Cuenta

/api/accounts/me, /api/account/connectors/claude/*

Cuándo usarla

Caso de uso	Ruta recomendada
Asistente de IA gestionando contenido	Servidor MCP: las herramientas abstraen la API y gestionan la autenticación
Integración del lado del servidor, CI/CD	API REST: mayor control, sin dependencia de cliente MCP
Receptor de Webhook	API REST

Ejemplo

Obtener detalles del proyecto con un token Bearer:

curl https://api.comstack.ai/api/projects/YOUR_PROJECT_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Llamar al endpoint MCP con una clave de servicio:

curl -X POST https://api.comstack.ai/mcp \
  -H "Content-Type: application/json" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -H "x-api-key: YOUR_SERVICE_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-project-state","arguments":{"project_id":"YOUR_PROJECT_ID"}}}'

Errores comunes

Error	Causa	Solución
`401 Unauthorized`	Token faltante o expirado	Reautenticar o regenerar la clave de API
`403 Trial expired`	El periodo de prueba del proyecto terminó	Actualiza el plan para restaurar el acceso
`403 Insufficient permission`	El rol del llamador es inferior al requerido	Verifica tu rol y asegúrate de usar las credenciales correctas
`413 Payload Too Large`	El cuerpo de la solicitud excede el límite	Reduce el tamaño de la carga o usa el endpoint de carga por partes
`429 Too Many Requests`	Límite de tasa alcanzado	Espera y reintenta tras el valor del encabezado `Retry-After`

Relacionado

Referencia de autenticación — tokens, claves de API, asignación de roles
Referencia de publicación — flujo de dos pasos de borrador a publicación
Servidor MCP — las mismas operaciones mediante herramientas MCP