Marques

Endpoints

Méthode	Chemin	Description
`GET`	`/brands`	Lister toutes les marques
`POST`	`/brands`	Créer une marque
`GET`	`/brands/{brandId}`	Obtenir les détails d'une marque
`PATCH`	`/brands/{brandId}`	Modifier une marque
`DELETE`	`/brands/{brandId}`	Supprimer une marque

GET /brands

Liste toutes les marques appartenant au compte authentifié.

curl https://mentova.ai/api/v1/brands \
  -H "X-API-Key: mtv_live_votre_cle"

Réponse `200`

{
  "data": [
    {
      "id": "clxabc123",
      "name": "Acme Corp",
      "domain": "acme.com",
      "aliases": ["Acme"],
      "language": "fr",
      "country": "FR",
      "autoWeeklyAnalysis": false,
      "createdAt": "2026-01-10T09:00:00.000Z"
    }
  ]
}

POST /brands

Crée une nouvelle marque. Le nombre de marques autorisées dépend de votre plan.

Corps de la requête

Champ	Type	Requis	Description
`name`	string	Oui	Nom de la marque (max 100 caractères)
`domain`	string	Non	Domaine de la marque (max 253 caractères)
`aliases`	string[]	Non	Noms alternatifs à surveiller
`language`	string	Non	Code de langue BCP-47, ex. `fr` (2-5 caractères)
`country`	string	Non	Code pays ISO 3166-1 alpha-2, ex. `FR` (2-5 caractères)

curl -X POST https://mentova.ai/api/v1/brands \
  -H "X-API-Key: mtv_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domain": "acme.com",
    "aliases": ["Acme"],
    "language": "fr",
    "country": "FR"
  }'

Réponse `201`

{
  "data": {
    "id": "clxabc123",
    "name": "Acme Corp",
    "domain": "acme.com",
    "aliases": ["Acme"],
    "language": "fr",
    "country": "FR",
    "autoWeeklyAnalysis": false,
    "createdAt": "2026-06-01T09:00:00.000Z"
  }
}

Erreurs

HTTP	code	Cause
`409`	`CONFLICT`	Une marque avec ce nom existe déjà
`422`	`VALIDATION_ERROR`	Corps de requête invalide
`422`	`LIMIT_REACHED`	Limite de marques du plan atteinte

GET /brands/

Obtient les détails complets d'une marque.

curl https://mentova.ai/api/v1/brands/clxabc123 \
  -H "X-API-Key: mtv_live_votre_cle"

Paramètres de chemin

Paramètre	Description
`brandId`	Identifiant de la marque

Réponse `200`

{
  "data": {
    "id": "clxabc123",
    "name": "Acme Corp",
    "domain": "acme.com",
    "aliases": ["Acme"],
    "language": "fr",
    "country": "FR",
    "autoWeeklyAnalysis": false,
    "createdAt": "2026-01-10T09:00:00.000Z"
  }
}

PATCH /brands/

Modifie un ou plusieurs champs d'une marque. Seuls les champs inclus dans le corps de la requête sont mis à jour.

Corps de la requête

Champ	Type	Requis	Description
`name`	string	Non	Nouveau nom (max 100 caractères)
`domain`	string \| null	Non	Nouveau domaine, ou `null` pour le supprimer
`aliases`	string[]	Non	Nouveau tableau d'alias
`language`	string	Non	Langue du marché principal (2-5 caractères, normalisée : `pt-BR` devient `pt`). Envoyée seule, elle remplace le marché principal, sans en ajouter un
`markets`	string[]	Non	Marchés suivis, au format `PAYS-langue` (`BE-fr`, `BE-nl`) ; le premier est le marché principal. Entre 1 et 100 entrées
`autoWeeklyAnalysis`	boolean	Non	Activer ou désactiver les campagnes hebdomadaires automatiques

Les marchés suivent les mêmes règles que dans l'application : un seul pendant l'essai de 14 jours (403, code MARKETS_TRIAL_LIMIT), autant que vous voulez sur un plan payant. Les langues des marchés supplémentaires doivent faire partie des langues d'analyse proposées (422 sinon). Un sujet ne peut être créé que dans un marché que la marque suit : ajoutez le marché ici avant de créer ses sujets (voir Sujets et prompts).

curl -X PATCH https://mentova.ai/api/v1/brands/clxabc123 \
  -H "X-API-Key: mtv_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"markets": ["BE-fr", "BE-nl"]}'

Réponse `200`

{
  "data": {
    "id": "clxabc123",
    "name": "Acme Corp",
    "domain": "acme.com",
    "autoWeeklyAnalysis": true
  }
}

DELETE /brands/

Supprime définitivement une marque et toutes les données associées.

curl -X DELETE https://mentova.ai/api/v1/brands/clxabc123 \
  -H "X-API-Key: mtv_live_votre_cle"

Réponse `200`

{
  "data": { "deleted": true }
}

Avatars

Les avatars d'audience définissent des profils persona utilisés pour contextualiser les prompts LLM lors des campagnes. Plafond selon le plan : 5 avatars par marque sur Pro, illimité à partir de Pro+.

Endpoints

Méthode	Chemin	Description
`GET`	`/brands/{brandId}/avatars`	Lister les avatars
`POST`	`/brands/{brandId}/avatars`	Créer un avatar
`PATCH`	`/brands/{brandId}/avatars/{avatarId}`	Modifier un avatar
`DELETE`	`/brands/{brandId}/avatars/{avatarId}`	Supprimer un avatar

GET /brands//avatars

curl https://mentova.ai/api/v1/brands/clxabc123/avatars \
  -H "X-API-Key: mtv_live_votre_cle"

Réponse `200`

{
  "data": [
    {
      "id": "clxavatar1",
      "brandId": "clxabc123",
      "name": "Sophie, Directrice Marketing",
      "sector": "SaaS B2B",
      "role": "Directrice Marketing",
      "objectives": "Augmenter le share of voice de la marque dans les résultats IA",
      "description": null,
      "isDefault": true,
      "createdAt": "2026-04-17T10:00:00.000Z",
      "updatedAt": "2026-04-17T10:00:00.000Z"
    }
  ]
}

POST /brands//avatars

Corps de la requête

Champ	Type	Requis	Description
`name`	string	Oui	Nom d'affichage de l'avatar (max 100 caractères)
`sector`	string	Oui	Secteur d'activité (max 100 caractères)
`role`	string	Oui	Rôle ou type de persona (max 100 caractères)
`objectives`	string	Oui	Objectifs et contexte de ce persona (max 500 caractères)
`description`	string	Non	Description longue optionnelle (max 1000 caractères)
`isDefault`	boolean	Non	Définir comme avatar par défaut pour les nouvelles campagnes

curl -X POST https://mentova.ai/api/v1/brands/clxabc123/avatars \
  -H "X-API-Key: mtv_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sophie, Directrice Marketing",
    "sector": "SaaS B2B",
    "role": "Directrice Marketing",
    "objectives": "Augmenter le share of voice de la marque dans les résultats IA",
    "isDefault": true
  }'

Réponse `201`

{
  "data": {
    "id": "clxavatar1",
    "brandId": "clxabc123",
    "name": "Sophie, Directrice Marketing",
    "sector": "SaaS B2B",
    "role": "Directrice Marketing",
    "objectives": "Augmenter le share of voice de la marque dans les résultats IA",
    "description": null,
    "isDefault": true,
    "createdAt": "2026-04-17T10:00:00.000Z",
    "updatedAt": "2026-04-17T10:00:00.000Z"
  }
}

PATCH /brands//avatars/

Tous les champs sont optionnels. Seuls les champs fournis sont mis à jour.

curl -X PATCH https://mentova.ai/api/v1/brands/clxabc123/avatars/clxavatar1 \
  -H "X-API-Key: mtv_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"isDefault": false}'

Réponse `200`

{
  "data": {
    "id": "clxavatar1",
    "isDefault": false
  }
}

DELETE /brands//avatars/

curl -X DELETE https://mentova.ai/api/v1/brands/clxabc123/avatars/clxavatar1 \
  -H "X-API-Key: mtv_live_votre_cle"

Réponse `200`

{
  "data": { "id": "clxavatar1" }
}

Endpoints

GET /brands

Réponse 200

POST /brands

Corps de la requête

Réponse 201

Erreurs

GET /brands/

Paramètres de chemin

Réponse 200

PATCH /brands/

Corps de la requête

Réponse 200

DELETE /brands/

Réponse 200

Avatars

Endpoints

GET /brands//avatars

Réponse 200

POST /brands//avatars

Corps de la requête

Réponse 201

PATCH /brands//avatars/

Réponse 200

DELETE /brands//avatars/

Réponse 200

Réponse `200`

Réponse `201`

Réponse `200`

Réponse `200`

Réponse `200`

Réponse `200`

Réponse `201`

Réponse `200`

Réponse `200`