Automations

3 endpoints

get/v1/automations

Lister les automations

Retourne la liste paginée des automations actives du client (cursor v2). Tri stable created_at DESC, id DESC. Les automations archivées (archived_at IS NOT NULL) sont exclues — l'API publique ne les expose pas.

Filtres

?status=active — uniquement les automations is_active=true.
?status=inactive — uniquement les automations is_active=false.

Lecture seule

L'API publique expose seulement la lecture (liste + historique) et le déclenchement manuel. La création/édition/archivage d'une automation passe par le dashboard — aucun endpoint POST/PATCH/DELETE /v1/automations n'existe.

Scopes requis: automations:read

Paramètres de requête

Nom	Type	obligatoire	Description
`status`	`string`	optionnel	Filtre `is_active=true` (active) ou `is_active=false` (inactive).

Responses

Status	Description
`200`	Liste paginée des automations.
`400`	La requête est mal formée (header manquant, JSON invalide, paramètre invalide).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/automations' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

post/v1/automations/{id}/trigger

Déclencher manuellement une automation

Crée une exécution status="pending" avec trigger_type="manual_api", réclamable par le moteur d'automations (asynchrone, pas de garantie de complétion synchrone). Pour suivre la progression de l'exécution, interroger GET /v1/automations/{id}/history.

Préconditions

L'automation doit appartenir au client appelant et ne pas être archivée — sinon 404 not_found.
L'automation doit avoir is_active=true — sinon 409 automation_inactive.
L'automation doit être publiée — sinon 409 automation_not_published.
L'automation publiée doit posséder un noeud déclencheur — sinon 409 no_trigger.
Le contact_id doit appartenir au client appelant — sinon 404 not_found.

Gardes d'enrôlement

Le déclenchement manuel passe par les mêmes gardes que les déclencheurs automatiques :

Contact déjà dans un parcours actif de cette automation — sinon 409 already_enrolled (activer la multi-opportunité dans les réglages d'enrôlement pour autoriser des parcours concurrents).
Doublon dans les 5 dernières minutes, plafond de 5 enrôlements par contact par 24 h sur cette automation, ou plafond global de 200 exécutions par heure pour le compte — sinon 429 trigger_throttled.

Le body accepte un event_data optionnel (objet JSON libre) injecté dans l'exécution et exploitable par les variables de template du graphe.

Scopes requis: automations:trigger

Corps de requête

#/components/schemas/AutomationTriggerInput

Responses

Status	Description
`201`	Exécution `pending` créée — réclamable par le moteur de manière asynchrone.
`400`	Validation des paramètres ou du body a échoué.
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`409`	La requête est syntaxiquement valide mais viole une règle métier.
`415`	Le header `Content-Type` est manquant ou non supporté pour cet endpoint.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X POST 'https://app.capturia.io/api/v1/automations/{id}/trigger' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "contact_id": "8f3b1a2c-9d4e-4f5a-b6c7-d8e9f0a1b2c3",
  "event_data": {
    "source": "crm_import"
  }
}'

get/v1/automations/{id}/history

Lister l'historique d'exécutions d'une automation

Retourne la liste paginée des exécutions d'une automation (cursor v2). Tri stable created_at DESC, id DESC — les exécutions récentes en premier. Une exécution représente un passage de l'automation pour un contact donné ; le moteur peut la redémarrer après échec (retry_count > 0).

L'automation doit appartenir au client appelant et ne pas être archivée — sinon 404 not_found.

Scopes requis: automations:read

Responses

Status	Description
`200`	Liste paginée des exécutions de l'automation.
`400`	La requête est mal formée (header manquant, JSON invalide, paramètre invalide).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/automations/{id}/history' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'