Skip to main content
Los endpoints de stages permiten modelar el flujo conversacional previo a publicar una versión de agente.
Autenticación requerida: API Key con los scopes blueprint-stages:read / blueprint-stages:write y stage-triggers:read / stage-triggers:write (según el verbo), más el header X-Workspace-Id. Los scopes se comparan exactos: no hay comodines.

​
Listar stages

GET /v1/agents/{agentId}/blueprints/{blueprintId}/stages Parámetros de query:
  • page, limit: paginación estándar (por defecto page=1, limit=20; el máximo de limit es 100).
  • filter: expresión del API Query Builder sobre id, blueprintId, name, title, goalPrompt, order, createdAt y updatedAt. Por ejemplo, ?filter=eq(name,"greeting").
El listado no acepta search ni status. La validación corre con whitelist y forbidNonWhitelisted, así que cualquier parámetro no declarado devuelve 400 («property search should not exist») en lugar de ignorarse. Para buscar por nombre o título usa filter; un stage tampoco tiene estado (active / archived): existe o no existe.
Respuesta:

​
Crear stage

POST /v1/agents/{agentId}/blueprints/{blueprintId}/stages Payload mínimo:
Campos clave:
  • name: slug alfanumérico (se usa como destino para triggers).
  • order: número entero que define la posición relativa.
  • metadata: objeto flexible para flags o configuraciones del workspace.

​
Actualizar stage

PATCH /v1/agents/{agentId}/blueprints/{blueprintId}/stages/{stageId} Permite modificar título, prompt, metadata u order. Se aceptan actualizaciones parciales.

​
Eliminar stage

DELETE /v1/agents/{agentId}/blueprints/{blueprintId}/stages/{stageId} Responde 204 sin cuerpo.
El borrado es físico y definitivo: no hay soft-delete. La fila del stage se elimina y la llave foránea de blueprint_stage_triggers borra en cascada todos sus triggers, sin forma de recuperarlos. Si lo que quieres es archivar un stage, guarda su definición (y la de sus triggers) antes de llamar a este endpoint.

​
Reordenar stages

POST /v1/agents/{agentId}/blueprints/{blueprintId}/stages:reorder
El array stageIds define el orden final (posición cero corresponde al primer stage). Si envías startingStageName, el blueprint actualizará automáticamente el punto de entrada del journey.

​
Triggers por stage

GET /v1/agents/{agentId}/blueprints/{blueprintId}/stages/{stageId}/triggers Respuesta paginada. Cada trigger trae id, stageId, condition.type, condition.value, nextStageName, createdAt y updatedAt. Un trigger no tiene metadata propia.

​
Crear trigger

POST /v1/agents/{agentId}/blueprints/{blueprintId}/stages/{stageId}/triggers
La condición sólo admite type y value; cualquier otra propiedad —metadata, por ejemplo— devuelve 400 («property metadata should not exist»).
  • type: intent, rule o expression.
  • value: cadena no vacía para intent y expression. Con type: "rule" acepta además un objeto plano, que se guarda tal cual.

​
Actualizar trigger

PATCH /v1/agents/{agentId}/blueprints/{blueprintId}/stages/{stageId}/triggers/{triggerId} Se puede actualizar sólo la condición, sólo el destino, o ambas propiedades.

​
Eliminar trigger

DELETE /v1/agents/{agentId}/blueprints/{blueprintId}/stages/{stageId}/triggers/{triggerId} Devuelve 204 No Content con el cuerpo vacío. No hay JSON que leer: un await res.json() sobre esta respuesta falla con error de parseo aunque el borrado haya salido bien.

​
BlueprintStageDraft template

Complementa estos endpoints utilizando el resource template MCP blueprintStageDraft. Entrega un JSON con orden recomendado, prompts base y triggers iniciales para acelerar documentación y sincronización. Consulta la sección Host MCP para detalles de uso.