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

# Workflow (JSON)

> Le format workflow_definition : graphe nodes/edges, workflow minimal valide, catalogue de node-types et validation.

## Vue d'ensemble

`workflow_definition` est le **JSON** qui représente un agent sous forme de
**graphe** (nœuds + arêtes). Le format est proche de ReactFlow.

```json theme={null}
{
  "nodes": [
    { "id": "1", "type": "startCall", "position": { "x": 0, "y": 0 }, "data": {} }
  ],
  "edges": []
}
```

> [!NOTE]
>
> Référence détaillée des nœuds : [Nœuds (graphe)](https://docs.bookivox.com/api-reference/nodes). Construire
> un workflow à la main est rare : le plus simple est de **partir d'un template**
> (voir [Flows](https://docs.bookivox.com/api-reference/flows)) ou de laisser un **agent IA** le générer
> (voir [Pour les agents IA](https://docs.bookivox.com/api-reference/guides/ai-agents)).

## Structure d'un nœud

| Champ | Type | Requis | Notes |
| - | - | - | - |
| `id` | string | oui | Identifiant unique dans le graphe. |
| `type` | string | oui | Type de nœud (ex. `startCall`). |
| `position` | `{x, y}` | oui | Position sur le canevas. |
| `data` | object | oui | Champs propres au nœud. Le schéma exact est décrit par le catalogue `node-types`. |

## Structure d'une arête

| Champ | Type | Requis | Notes |
| - | - | - | - |
| `id` | string | oui | Identifiant unique. |
| `source` | string | oui | `id` du nœud de départ. |
| `target` | string | oui | `id` du nœud d'arrivée. |
| `data.label` | string | oui | Libellé (non vide). |
| `data.condition` | string | oui | Condition (ex. `"always"`). |

## Workflow minimal valide

`startCall` → `agentNode` → `endCall` :

```json theme={null}
{
  "nodes": [
    {
      "id": "start",
      "type": "startCall",
      "position": { "x": 0, "y": 0 },
      "data": { "name": "Start", "prompt": "Greet the caller.", "is_start": true }
    },
    {
      "id": "agent",
      "type": "agentNode",
      "position": { "x": 260, "y": 0 },
      "data": { "name": "Agent", "prompt": "Help the caller." }
    },
    {
      "id": "end",
      "type": "endCall",
      "position": { "x": 520, "y": 0 },
      "data": { "name": "End", "prompt": "Thank and hang up.", "is_end": true }
    }
  ],
  "edges": [
    {
      "id": "start-agent",
      "source": "start",
      "target": "agent",
      "data": { "label": "Start", "condition": "always" }
    },
    {
      "id": "agent-end",
      "source": "agent",
      "target": "end",
      "data": { "label": "Close", "condition": "always" }
    }
  ]
}
```

## Types de nœuds

| `type` | Rôle |
| - | - |
| `startCall` | Point d'entrée de l'appel |
| `agentNode` | Cœur conversationnel (prompt, outils, documents) |
| `endCall` | Fin d'appel |
| `globalNode` | Contexte/instructions globales |
| `trigger` | Déclencheur API |
| `webhook` | Appel sortant HTTP |
| `qa` | Analyse qualité |

## Découvrir et valider

* **Catalogue** : `GET /api/v1/api/node-types` et `/node-types/{name}`. Chaque
  entrée décrit un `NodeSpec` : le schéma exact des champs de `data`.
* **Validation** : `POST /api/v1/api/workflow/{workflow_id}/validate`

Le détail des types de champs (`PropertySpec`, `PropertyType`) est documenté dans
[Nœuds (graphe)](https://docs.bookivox.com/api-reference/nodes).

En cas d'échec, la réponse `422` contient :

```json theme={null}
{
  "is_valid": false,
  "errors": [
    { "kind": "node", "id": "agent", "field": "prompt", "message": "..." }
  ]
}
```

> [!WARNING]
>
> Les nœuds `startCall`, `agentNode` et `endCall` exigent un `prompt` **non vide**.
> Les arêtes exigent `data.label` et `data.condition` **non vides**.

> **[Nœuds (graphe)](https://docs.bookivox.com/api-reference/nodes)**
>
> Référence complète.

> **[Flows](https://docs.bookivox.com/api-reference/flows)**
>
> Créer, valider, publier.

> **[Pour les agents IA](https://docs.bookivox.com/api-reference/guides/ai-agents)**
>
> Générer un workflow par IA.

> **[Référence API](https://docs.bookivox.com/api-reference/overview)**
>
> Piloter par REST.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.