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 scopes blueprint-stages:* ystage-triggers:* (según el verbo), más el header X-Workspace-Id.

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).
  • search: filtra por coincidencias en name o title.
  • status: opcional (active, archived).
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} Realiza soft-delete. Los triggers asociados quedan inactivos hasta que se reasignan.

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 con campos condition.type, condition.value, metadata y nextStageName.

Crear trigger

POST /v1/agents/{agentId}/blueprints/{blueprintId}/stages/{stageId}/triggers

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 { "status": "deleted" } si la operación fue exitosa.

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.