Documentación de la API

Base URL: /api

Descargar colección Postman Esquema OpenAPI (JSON)

Autenticación

Rutas que requieren usuario aceptan:

Método	Descripción
`Sesión`	Cookie (navegador)
`Authorization: Bearer <idToken>`	Token Firebase (web)
`X-API-Key` o `Authorization: Bearer <soma_...>`	API key — se genera en Configuración

Health

GET /api/health

Comprueba que el servidor responde. Sin autenticación.

Responses

Code	Schema
`200`	`{ "ok": true }`

Generate

POST /api/generate

Genera un proceso BPMN desde texto. Acepta JSON o multipart (.txt, .pdf, .docx, .xlsx).

Request body (application/json)

Nombre	Tipo	Requerido	Descripción
`transcript`	string	Sí	Descripción o transcripción del proceso
`redesign`	boolean	No	Si true, aplica mejores prácticas BPMN

{
  "transcript": "Cuando recibimos una factura, la validamos...",
  "redesign": false
}

Responses

Code	Schema
`200`	`{ "bpmnXml", "processName", "processDescription", "recommendations", "transcript" }`
`400`	`{ "error", "suggestion" }`

Diagramas

Todas las rutas requieren autenticación.

GET /api/diagrams

Lista los diagramas del usuario.

Query parameters

Nombre	Tipo	Descripción
`projectId`	string	Filtrar por proyecto
`tag`	string	Filtrar por etiqueta

Responses

200 → { "diagrams": [ { "id", "name", "processDescription", "bpmnXml", "createdAt", ... } ] }

GET /api/diagrams/{id}

Obtiene un diagrama por ID.

Path parameters

Nombre	Descripción
`id`	ID del diagrama

200 → { "diagram": { ... } }

POST /api/diagrams

Crea un nuevo diagrama.

Request body

Nombre	Tipo	Requerido
`name`	string	Sí
`bpmnXml`	string	Sí
`transcript`	string	No
`processDescription`	string	No
`recommendations`	array	No
`projectId`	string	No
`tags`	array	No

200 → { "diagram": { "id", "name", ... } }

PUT /api/diagrams/{id}

Actualiza un diagrama (campos parciales).

200 → { "diagram": { ... } }

DELETE /api/diagrams/{id}

Elimina un diagrama.

200 sin cuerpo

GET /api/diagrams/{id}/versions

Lista versiones del diagrama. Query: limit (opcional).

POST /api/diagrams/{id}/chat

Chat con el diagrama (asistente). Body: { "message", "history?", "bpmnXml?" }. Respuesta puede incluir bpmnXml actualizado.

Projects

GET /api/projects

Lista los proyectos del usuario.

200 → { "projects": [ { "id", "name", "createdAt", "updatedAt" }, ... ] }

POST /api/projects

Crea un proyecto. Body: { "name" }.

201 → { "project": { "id", "name", ... } }

GET /api/projects/{id}

Obtiene un proyecto por ID con el número de diagramas asignados.

200 → { "project": { ... }, "diagramCount": number }

PUT /api/projects/{id}

Actualiza un proyecto. Body: { "name" }.

200 → { "project": { ... } }

DELETE /api/projects/{id}

Elimina un proyecto. Los diagramas asignados pasan a "Sin proyecto".

200 → { "success": true, "unassignedCount": number }

Settings (API key)

GET /api/settings/api-key

Indica si el usuario tiene API key. 200 → { "hasKey": true|false }

POST /api/settings/api-key/generate

Genera una nueva API key. 200 → { "apiKey": "soma_..." } (solo una vez).

POST /api/settings/api-key/revoke

Revoca la API key actual. 200 → { "ok": true }

Otros

POST /api/analyze-bpmn

Analiza el proceso. Body: { "bpmnXml" }. Requiere auth.

POST /api/redesign-bpmn

Rediseña el BPMN. Body: { "bpmnXml", "instructions?" }. Requiere auth.

POST /api/transcribe

Transcribe audio (Whisper). Body: { "audio": "base64..." }.

POST /api/extract-text

Extrae texto de archivo. Multipart: .pdf, .docx, .xlsx.

Configuración · Genera tu API key para scripts o el servidor MCP (Cursor).