{"openapi":"3.1.0","info":{"title":"Mentova API","version":"1.0.0","description":"REST API for Agency accounts. Authenticate with X-API-Key header."},"servers":[{"url":"https://mentova.ai/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}},"paths":{"/brands":{"get":{"summary":"List brands","operationId":"listBrands","responses":{"200":{"description":"List of brands"},"401":{"description":"Invalid or missing API key"}}},"post":{"summary":"Create brand","operationId":"createBrand","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"domain":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"language":{"type":"string"},"country":{"type":"string"}}}}}},"responses":{"201":{"description":"Brand created"},"422":{"description":"Validation error or brand limit reached"}}}},"/brands/{brandId}":{"get":{"summary":"Get brand","operationId":"getBrand","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Brand details"},"404":{"description":"Not found"}}},"patch":{"summary":"Update brand","operationId":"updateBrand","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated brand"}}},"delete":{"summary":"Delete brand","operationId":"deleteBrand","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/brands/{brandId}/topics":{"get":{"summary":"List topics","operationId":"listTopics","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Topics list"}}},"post":{"summary":"Create topic","operationId":"createTopic","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seed"],"properties":{"seed":{"type":"string","minLength":3,"maxLength":200},"language":{"type":"string"},"country":{"type":"string"}}}}}},"responses":{"201":{"description":"Topic created"}}}},"/brands/{brandId}/topics/{topicId}":{"delete":{"summary":"Delete topic","operationId":"deleteTopic","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"topicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/brands/{brandId}/prompts":{"get":{"summary":"List prompts","operationId":"listPrompts","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"model","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Paginated prompts"}}}},"/brands/{brandId}/campaigns":{"get":{"summary":"List campaigns","operationId":"listCampaigns","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaigns list"}}},"post":{"summary":"Launch campaign","operationId":"launchCampaign","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topicId"],"properties":{"topicId":{"type":"string"},"models":{"type":"array","items":{"type":"string"}},"runsPerModel":{"type":"integer"}}}}}},"responses":{"201":{"description":"Campaign launched"},"422":{"description":"Quota exceeded or no prompts"}}}},"/brands/{brandId}/campaigns/{campaignId}":{"get":{"summary":"Get campaign status","operationId":"getCampaign","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign details and status"}}}},"/brands/{brandId}/visibility":{"get":{"summary":"Get visibility metrics","operationId":"getVisibility","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","default":30}},{"name":"model","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"SOV, timeline, mention rate"}}}},"/brands/{brandId}/competitors":{"get":{"summary":"List competitors","operationId":"listCompetitors","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Competitor leaderboard"}}}},"/brands/{brandId}/opportunities":{"get":{"summary":"List opportunities","operationId":"listOpportunities","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["NEW","REVIEWED","IN_PROGRESS","DONE","DISMISSED"]}}],"responses":{"200":{"description":"Opportunities list"}}}},"/brands/{brandId}/opportunities/{opportunityId}":{"patch":{"summary":"Update opportunity status","operationId":"updateOpportunity","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"opportunityId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["NEW","REVIEWED","IN_PROGRESS","DONE","DISMISSED"]}}}}}},"responses":{"200":{"description":"Updated opportunity"}}}},"/brands/{brandId}/sources":{"get":{"summary":"List sources","operationId":"listSources","parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sources list"}}}},"/brands/{brandId}/avatars":{"get":{"operationId":"listAvatars","summary":"List avatars for a brand","tags":["Avatars"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of avatars"}}},"post":{"operationId":"createAvatar","summary":"Create an avatar","tags":["Avatars"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sector","role","objectives"],"properties":{"name":{"type":"string"},"sector":{"type":"string"},"role":{"type":"string"},"objectives":{"type":"string"},"description":{"type":"string"},"isDefault":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Avatar created"},"422":{"description":"Validation error or avatar limit reached"}}}},"/brands/{brandId}/avatars/{avatarId}":{"patch":{"operationId":"updateAvatar","summary":"Update an avatar","tags":["Avatars"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"avatarId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"sector":{"type":"string"},"role":{"type":"string"},"objectives":{"type":"string"},"description":{"type":"string"},"isDefault":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Avatar updated"},"404":{"description":"Brand or avatar not found"}}},"delete":{"operationId":"deleteAvatar","summary":"Delete an avatar","tags":["Avatars"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"brandId","in":"path","required":true,"schema":{"type":"string"}},{"name":"avatarId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Avatar deleted"},"404":{"description":"Brand or avatar not found"}}}},"/keys":{"get":{"summary":"List API keys","operationId":"listKeys","responses":{"200":{"description":"API keys (without hashes)"}}},"post":{"summary":"Generate API key","operationId":"generateKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"New key (shown once in plain text)"}}}},"/keys/{keyId}":{"delete":{"summary":"Revoke API key","operationId":"revokeKey","parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"}}}}}}