Capabilities

Workflows

Exécutez des automations multi-étapes définies par l'utilisateur sur le vault. Les workflows sont rédigés dans le tableau de bord et déclenchés depuis votre backend via l'API publique.

Cycle de vie

Chaque exécution de workflow suit le même schéma :

Appelez capability avec l'ID du workflow et des entrées optionnelles.
Obtenez un field. L'exécution démarre dans l'état state.
Interrogez capability toutes les 2–5 secondes.
Les états d'exécution transitent : states.
Quand condition, le champ field contient le résultat.

La rédaction est uniquement depuis le tableau de bord

L'API publique n'expose pas la création ou l'édition de workflow. Construisez le workflow une fois dans le tableau de bord, copiez son ID, puis exécutez-le depuis le code.

workflows.list

GET/api/v2/workflows

Listez les workflows disponibles à l'utilisateur de la clé API.

scope: workflows:readcost: 1

Requête

bash
curl -sS "https://api.alloovium.com/api/v2/workflows?limit=25" \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

Réponse

json
{
  "data": [
    {
      "id": "wf_1f02d9ef-...",
      "name": "Weekly submittal review",
      "description": "Scan new submittals for noncompliance and summarise.",
      "enabled": true,
      "trigger_type": "manual",
      "created_at": "2026-03-12T08:00:00+00:00",
      "updated_at": "2026-04-01T12:14:00+00:00"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

workflows.run

POST/api/v2/workflows/{workflow_id}/runs

Démarrez une nouvelle exécution d'un workflow. Retourne un run_id que vous interrogez pour le statut.

scope: workflows:writecost: 25

Corps de requête

json
{
  "inputs": {
    "start_date": "2026-04-01",
    "end_date": "2026-04-08"
  },
  "project_id": "8f2e3c1a-..."
}

field — map optionnel des variables d'entrée déclarées du workflow.
field — portée optionnelle. Requise pour les workflows qui référencent des blocs block.

bash
curl -sS https://api.alloovium.com/api/v2/workflows/wf_1f02d9ef-.../runs \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY" \
  -H "Idempotency-Key: weekly-review-2026-04-08" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"start_date": "2026-04-01", "end_date": "2026-04-08"},
    "project_id": "8f2e3c1a-..."
  }'

Réponse

json
{
  "run_id": "run_c1d2e3f4-...",
  "workflow_id": "wf_1f02d9ef-...",
  "status": "pending",
  "started_at": null
}

Attachez un Idempotency-Key

Les exécutions de workflow coûtent 25 tokens et produisent des effets de bord. Une clé d'idempotence garantit qu'une réponse perdue ne déclenche pas deux fois la même exécution — voir Idempotence.

workflows.get_run_status

GET/api/v2/workflows/runs/{run_id}

Interrogez la progression d'une exécution, l'étape, les sorties et l'état d'erreur.

scope: workflows:readcost: 1

Réponse (en cours)

json
{
  "run_id": "run_c1d2e3f4-...",
  "workflow_id": "wf_1f02d9ef-...",
  "status": "running",
  "progress": 42,
  "stage": "Analysing submittals",
  "inputs": {"start_date": "2026-04-01", "end_date": "2026-04-08"},
  "outputs": null,
  "error_message": null,
  "started_at": "2026-04-08T10:12:05+00:00",
  "completed_at": null,
  "created_at": "2026-04-08T10:12:00+00:00"
}

Réponse (terminé)

json
{
  "run_id": "run_c1d2e3f4-...",
  "workflow_id": "wf_1f02d9ef-...",
  "status": "completed",
  "progress": 100,
  "stage": "done",
  "inputs": {"start_date": "2026-04-01", "end_date": "2026-04-08"},
  "outputs": {
    "summary": "5 submittals reviewed, 2 flagged for non-compliance.",
    "items": [
      {"document_id": "4a1c2b3d-...", "status": "non-compliant", "reason": "..."}
    ]
  },
  "error_message": null,
  "started_at": "2026-04-08T10:12:05+00:00",
  "completed_at": "2026-04-08T10:14:18+00:00",
  "created_at": "2026-04-08T10:12:00+00:00"
}

États de statut

Statut	Terminal ?	Notes
pending	no	Queued; not yet claimed by a worker.
running	no	Currently executing. progress + stage update as it runs.
completed	yes	Finished successfully. outputs is populated.
failed	yes	Runtime error. error_message contains a human-readable reason.
cancelled	yes	Cancelled by the user or by a timeout. outputs may be null or partial.

Pattern d'interrogation

python
import time, httpx

def wait_for_run(run_id: str, api_key: str, timeout_s: int = 900):
    url = f"https://api.alloovium.com/api/v2/workflows/runs/{run_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.monotonic() + timeout_s

    while time.monotonic() < deadline:
        resp = httpx.get(url, headers=headers)
        resp.raise_for_status()
        payload = resp.json()
        status = payload["status"]

        if status in ("completed", "failed", "cancelled"):
            return payload

        time.sleep(3)  # 2-5s polling is ideal

    raise TimeoutError(f"run {run_id} did not finish in {timeout_s}s")

Ne faites pas de boucle serrée

L'interrogation coûte 1 token par appel. Une boucle de 3 secondes sur une exécution de 10 minutes coûte ~200 tokens ; une boucle serrée de 50ms épuiserait votre bucket en quelques secondes et vous vaudrait un 429.

Voir aussi

Templates — les jobs de remplissage de documents utilisent le même schéma pending/interrogation.
Idempotence — ne déclenchez jamais la même exécution deux fois.