Tags

2 endpoints

get/v1/tags

Lister les 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 évite qu'un doublon de nom (autorisé en base) ne provoque skip ou duplication entre pages.

Sanitization du curseur

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

Responses

Status	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.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/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.

Aucune contrainte d'unicité sur name — deux tags peuvent partager le même nom (différenciés par leur id et color).

Scopes requis: tags:write

Corps de requête

#/components/schemas/TagCreate

Responses

Status	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.
`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/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"
}'