Tags

2 endpoints

get/v1/tags

Retourne la liste paginée des tags du client (cursor v2). Tri stable name ASC, id ASC — l'ordre alphabétique facilite la construction d'une UI de sélection. Le tiebreaker id ASC garantit un ordre total entre les pages (noms uniques dans le compte, sensibles à la casse).

Le name étant user-controlled, le curseur encode les valeurs avec échappement PostgREST côté serveur — pas d'action requise côté client.

Scopes requis: tags:read

Statut	Description
`200`	Liste paginée des tags.
`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.

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

post/v1/tags

Créer un tag

Crée un nouveau tag dans la bibliothèque du client. Seul name est obligatoire — color reçoit la valeur par défaut #6b7280 (gris neutre) si non fournie. Pour attacher le tag à un contact existant, utiliser POST /v1/contacts/{id}/tags avec l'identifiant retourné par cet endpoint.

Le nom est unique dans le compte : un nom déjà pris retourne 409 duplicate_resource. Un nom qui commence par « Campagne : » (casse et espaces libres) est réservé aux tags de campagne gérés par Capturia et retourne 400 validation_error, avec details: { field: "name", reason: "reserved_prefix" }. Un name absent retourne 400 validation_error avec details: { field: "name", reason: "required" }.

Scopes requis: tags:write

Corps de requête

Propriété	Type	Obligatoire	Description
`name`	`string`	obligatoire	Nom affiché du tag.
`color`	`string`	optionnel	Couleur hexadécimale `#RRGGBB`. Défaut serveur `#6b7280`.
`description`	`string`	optionnel	Description libre.
`category`	`string`	optionnel	Catégorie de regroupement.

Responses

Statut	Description
`201`	Tag créé.
`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.
`409`	Une ressource avec un identifiant unique conflictuel existe déjà.
`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://api.capturia.io/v1/tags' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Lead chaud",
  "color": "#ef4444",
  "description": "Prospect avec budget confirmé et calendrier court.",
  "category": "priority"
}'

Tags

Lister les tags

Sanitization du curseur

Responses

Exemple de requête

Créer un tag

Corps de requête

Responses

Exemple de requête