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:* y stage-triggers:* (según el verbo), más el header 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: 
{
  "data": [
    {
      "id": "e5d7...",
      "name": "greeting",
      "title": "Saludo inicial",
      "goalPrompt": "Da la bienvenida...",
      "order": 0,
      "metadata": { "expectedDurationSeconds": 60 },
      "triggers": [
        {
          "id": "c2f3...",
          "condition": { "type": "intent", "value": "collect_requirements" },
          "nextStageName": "requirements"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "hasNext": false,
    "hasPrevious": false
  }
}

​
Crear stage

POST /v1/agents/{agentId}/blueprints/{blueprintId}/stages Payload mínimo: 
{
  "name": "proposal",
  "goalPrompt": "Explica la solución recomendada...",
  "order": 2,
  "title": "Propuesta",
  "metadata": { "requiresSupervisor": false }
}
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 
{
  "stageIds": ["greeting-id", "requirements-id", "proposal-id"],
  "startingStageName": "greeting"
}
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 
{
  "condition": {
    "type": "intent",
    "value": "schedule_call",
    "metadata": { "confidence": 0.8 }
  },
  "nextStageName": "handoff"
}

​
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.