> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stages y triggers

> Endpoints REST para manejar stages de blueprint y sus triggers conversacionales.

Los endpoints de stages permiten modelar el flujo conversacional previo a publicar una versión de agente.

<Info>
  Autenticación requerida: API Key con scopes{' '}
  <code>blueprint-stages:\*</code> y<code>stage-triggers:\*</code> (según
  el verbo), más el header
  <code>X-Workspace-Id</code>.
</Info>

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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](../mcp) para detalles de uso.