Endpoints
| Method | Path | Description |
|---|---|---|
GET | /brands | List all brands |
POST | /brands | Create a brand |
GET | /brands/{brandId} | Get brand details |
PATCH | /brands/{brandId} | Update a brand |
DELETE | /brands/{brandId} | Delete a brand |
GET /brands
List all brands belonging to the authenticated account.
curl https://mentova.ai/api/v1/brands \
-H "X-API-Key: mtv_live_your_key"
Response 200
{
"data": [
{
"id": "clxabc123",
"name": "Acme Corp",
"domain": "acme.com",
"aliases": ["Acme"],
"language": "en",
"country": "US",
"autoWeeklyAnalysis": false,
"createdAt": "2026-01-10T09:00:00.000Z"
}
]
}
POST /brands
Create a new brand. The number of brands allowed depends on your plan.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Brand name (max 100 chars) |
domain | string | No | Brand domain (max 253 chars) |
aliases | string[] | No | Alternative names to track |
language | string | No | BCP-47 language code, e.g. en (2-5 chars) |
country | string | No | ISO 3166-1 alpha-2 country code, e.g. US (2-5 chars) |
curl -X POST https://mentova.ai/api/v1/brands \
-H "X-API-Key: mtv_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Corp",
"domain": "acme.com",
"aliases": ["Acme"],
"language": "en",
"country": "US"
}'
Response 201
{
"data": {
"id": "clxabc123",
"name": "Acme Corp",
"domain": "acme.com",
"aliases": ["Acme"],
"language": "en",
"country": "US",
"autoWeeklyAnalysis": false,
"createdAt": "2026-06-01T09:00:00.000Z"
}
}
Error responses
| HTTP | code | Cause |
|---|---|---|
409 | CONFLICT | A brand with this name already exists |
422 | VALIDATION_ERROR | Invalid request body |
422 | LIMIT_REACHED | Brand limit for your plan has been reached |
GET /brands/
Get full details for a single brand.
curl https://mentova.ai/api/v1/brands/clxabc123 \
-H "X-API-Key: mtv_live_your_key"
Path parameters
| Parameter | Description |
|---|---|
brandId | ID of the brand |
Response 200
{
"data": {
"id": "clxabc123",
"name": "Acme Corp",
"domain": "acme.com",
"aliases": ["Acme"],
"language": "en",
"country": "US",
"autoWeeklyAnalysis": false,
"createdAt": "2026-01-10T09:00:00.000Z"
}
}
PATCH /brands/
Update one or more fields on a brand. Only fields included in the request body are changed.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | New name (max 100 chars) |
domain | string | null | No | New domain, or null to clear it |
aliases | string[] | No | Replacement aliases array |
language | string | No | BCP-47 language code (2-5 chars) |
autoWeeklyAnalysis | boolean | No | Enable or disable automatic weekly campaigns |
curl -X PATCH https://mentova.ai/api/v1/brands/clxabc123 \
-H "X-API-Key: mtv_live_your_key" \
-H "Content-Type: application/json" \
-d '{"autoWeeklyAnalysis": true}'
Response 200
{
"data": {
"id": "clxabc123",
"name": "Acme Corp",
"domain": "acme.com",
"autoWeeklyAnalysis": true
}
}
DELETE /brands/
Permanently delete a brand and all associated data.
curl -X DELETE https://mentova.ai/api/v1/brands/clxabc123 \
-H "X-API-Key: mtv_live_your_key"
Response 200
{
"data": { "deleted": true }
}
Avatars
Audience avatars define persona profiles used to contextualise LLM prompts during campaigns. Maximum 5 avatars per brand.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /brands/{brandId}/avatars | List avatars |
POST | /brands/{brandId}/avatars | Create an avatar |
PATCH | /brands/{brandId}/avatars/{avatarId} | Update an avatar |
DELETE | /brands/{brandId}/avatars/{avatarId} | Delete an avatar |
GET /brands//avatars
curl https://mentova.ai/api/v1/brands/clxabc123/avatars \
-H "X-API-Key: mtv_live_your_key"
Response 200
{
"data": [
{
"id": "clxavatar1",
"brandId": "clxabc123",
"name": "Sarah, CMO",
"sector": "SaaS B2B",
"role": "Chief Marketing Officer",
"objectives": "Grow brand share of voice in AI search results",
"description": null,
"isDefault": true,
"createdAt": "2026-04-17T10:00:00.000Z",
"updatedAt": "2026-04-17T10:00:00.000Z"
}
]
}
POST /brands//avatars
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Avatar display name (max 100 chars) |
sector | string | Yes | Industry or sector (max 100 chars) |
role | string | Yes | Job role or persona type (max 100 chars) |
objectives | string | Yes | Goals and context for this persona (max 500 chars) |
description | string | No | Optional longer description (max 1000 chars) |
isDefault | boolean | No | Set as default avatar for new campaigns |
curl -X POST https://mentova.ai/api/v1/brands/clxabc123/avatars \
-H "X-API-Key: mtv_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Sarah, CMO",
"sector": "SaaS B2B",
"role": "Chief Marketing Officer",
"objectives": "Grow brand share of voice in AI search results",
"isDefault": true
}'
Response 201
{
"data": {
"id": "clxavatar1",
"brandId": "clxabc123",
"name": "Sarah, CMO",
"sector": "SaaS B2B",
"role": "Chief Marketing Officer",
"objectives": "Grow brand share of voice in AI search results",
"description": null,
"isDefault": true,
"createdAt": "2026-04-17T10:00:00.000Z",
"updatedAt": "2026-04-17T10:00:00.000Z"
}
}
PATCH /brands//avatars/
All fields are optional. Only provided fields are updated.
curl -X PATCH https://mentova.ai/api/v1/brands/clxabc123/avatars/clxavatar1 \
-H "X-API-Key: mtv_live_your_key" \
-H "Content-Type: application/json" \
-d '{"isDefault": false}'
Response 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_your_key"
Response 200
{
"data": { "id": "clxavatar1" }
}