{"openapi": "3.1.0", "info": {"title": "Brand DNA API", "version": "1.0.0", "description": "One brand name in: reads the official site, ads and search data, and returns an evidence-graded Brand DNA (purpose, voice, design, products, ads, market perception). Workflow: estimate_run → start_run → get_run_status → get_run → get_guardrails", "contact": {"email": "m-support@listeningmind.com"}}, "servers": [{"url": "https://brand-dna.listeningmind.ai"}], "paths": {"/api/estimate": {"post": {"operationId": "estimate_run", "summary": "Estimate", "description": "Price and expected duration of one Brand DNA run. Free. Read only, free. Usually followed by: start_run.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"brand": {"type": "string", "description": "brand name as people know it"}, "market": {"type": "string", "enum": ["us", "jp", "kr"], "default": "us", "description": "market: us, jp or kr"}, "deep": {"type": "boolean", "default": false, "description": "also read search paths"}, "competitors": {"type": "array", "items": {"type": "string"}, "maxItems": 5, "description": "Competitor brands to measure share of search and AI answers against (otherwise picked from the search data)"}}, "required": ["brand"]}}}}}}, "/api/runs": {"post": {"operationId": "start_run", "summary": "Extract Brand DNA", "description": "Starts a Brand DNA run: resolves the brand, finds official domains for the market, maps the site, reads purpose (L0), identity, voice, design, products and ads, reads ListeningMind search and AI-answer data, and writes the DNA with evidence grades. Takes 4-10 minutes. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: 500 Lima a run (launch price; list 5,000 Lima). Usually followed by: get_run_status.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "500 Lima a run (launch price; list 5,000 Lima)", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"brand": {"type": "string", "description": "brand name as people know it"}, "market": {"type": "string", "enum": ["us", "jp", "kr"], "default": "us", "description": "market: us, jp or kr"}, "lang": {"type": "string", "enum": ["en", "ja", "ko", "es"], "default": "en", "description": "language of the written DNA"}, "domain": {"type": "string", "description": "official domain or start URL if known (a path scopes a sub-brand)"}, "category": {"type": "string", "description": "category hint"}, "deep": {"type": "boolean", "default": false, "description": "also read search paths (Path Finder)"}, "competitors": {"type": "array", "items": {"type": "string"}, "maxItems": 5, "description": "Competitor brands to measure share of search and AI answers against (otherwise picked from the search data)"}}, "required": ["brand"]}}}}}, "get": {"operationId": "list_runs", "summary": "Runs", "description": "Your runs, newest first. Read only, free.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "limit", "in": "query", "required": false, "description": "how many", "schema": {"type": "integer", "default": 100}}]}}, "/api/suggest": {"post": {"operationId": "suggest_brands", "summary": "Find rival brands", "description": "AI input helper for a category set. Give a category name or your own brand; returns 8-10 brands people search in that category (or together with the brand) with their monthly searches and trend, plus the category as people search it. Search data first; the model only names brands from it and tops up with known rivals when the data is thin. Changes saved data in the app; no credits. Usually followed by: start_set.", "tags": ["action"], "x-lm-kind": "action", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "description": "a category name or your own brand"}, "kind": {"type": "string", "enum": ["brand", "category"], "default": "brand", "description": "brand: find its rivals; category: find the brands in it"}, "market": {"type": "string", "enum": ["us", "jp", "kr"], "default": "us", "description": "market: us, jp or kr"}, "lang": {"type": "string", "enum": ["en", "ja", "ko", "es"], "default": "en", "description": "language of the labels"}}, "required": ["query"]}}}}}}, "/api/sets": {"post": {"operationId": "start_set", "summary": "Category set analysis", "description": "Analyzes 2 to 5 brands in one category the same way and shows their positions: share of search, share of AI answers, fit at each step of the customer journey, a positioning map, what each brand owns, category codes, white space and the next moves for your brand. Every brand gets a full Brand DNA measured on the same category terms and the same rival set; Brand DNAs you made in the last 30 days are reused; only your brand gets the playbook and AI skill package. Takes 15-40 minutes. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: 1,500 Lima a set of up to 5 brands (launch price; list 15,000 Lima). Usually followed by: get_run_status, get_run.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "1,500 Lima a set of up to 5 brands (launch price; list 15,000 Lima)", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"brands": {"type": "array", "minItems": 2, "maxItems": 5, "description": "2 to 5 brands; mark exactly one as your own", "items": {"type": "object", "properties": {"name": {"type": "string", "description": "brand name as people know it"}, "own": {"type": "boolean", "description": "true for your own brand"}, "domain": {"type": "string", "description": "official domain if known"}}, "required": ["name"]}}, "market": {"type": "string", "enum": ["us", "jp", "kr"], "default": "us", "description": "market: us, jp or kr"}, "lang": {"type": "string", "enum": ["en", "ja", "ko", "es"], "default": "en", "description": "language of the written result"}, "category": {"type": "string", "description": "the category as people search it (from suggest_brands)"}}, "required": ["brands"]}}}}}}, "/api/runs/{run_id}/status": {"get": {"operationId": "get_run_status", "summary": "Status", "description": "Status, stage and progress of a run. Read only, free. Usually followed by: get_run.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "run_id", "in": "path", "required": true, "description": "run id from start_run", "schema": {"type": "string"}}]}}, "/api/runs/{run_id}": {"get": {"operationId": "get_run", "summary": "Result", "description": "The run and, when done, its Brand DNA document. Read only, free. Usually followed by: get_guardrails, compare_dna.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "run_id", "in": "path", "required": true, "description": "run id", "schema": {"type": "string"}}]}, "delete": {"operationId": "delete_run", "summary": "Delete", "description": "Delete one of your runs. Deletes data. A person approves it first.", "tags": ["delete"], "x-lm-kind": "delete", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "run_id", "in": "path", "required": true, "description": "run id", "schema": {"type": "string"}}]}}, "/api/dna": {"get": {"operationId": "list_dna", "summary": "My Brand DNA", "description": "Your Brand DNA documents (latest version each). Read only, free.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "market", "in": "query", "required": false, "description": "filter by market", "schema": {"type": "string"}}, {"name": "category", "in": "query", "required": false, "description": "filter by category text", "schema": {"type": "string"}}]}}, "/api/dna/{dna_id}": {"get": {"operationId": "get_dna", "summary": "Brand DNA", "description": "One Brand DNA document by id (latest or a given version). Read only, free.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "dna_id", "in": "path", "required": true, "description": "Brand DNA id, e.g. us-patagonia", "schema": {"type": "string"}}, {"name": "version", "in": "query", "required": false, "description": "version number", "schema": {"type": "integer"}}]}}, "/api/dna/{dna_id}/guardrails": {"get": {"operationId": "get_guardrails", "summary": "Guardrails", "description": "Asset-production pack for other apps (Creative Finder, Brand Naming). People get the same rules as a downloadable Claude skill, ChatGPT GPT or Gemini gem from the report page. Read only, free.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "dna_id", "in": "path", "required": true, "description": "Brand DNA id", "schema": {"type": "string"}}]}}, "/api/compare": {"post": {"operationId": "compare_dna", "summary": "Compare", "description": "Compares Brand DNAs: brand vs brand, products, or a category (codes and white space). Uses a little model time. Changes saved data in the app; no credits.", "tags": ["action"], "x-lm-kind": "action", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"dna_ids": {"type": "array", "items": {"type": "string"}, "description": "Brand DNA ids to compare"}, "mode": {"type": "string", "enum": ["brands", "category", "products"], "description": "comparison mode"}, "lang": {"type": "string", "enum": ["en", "ja", "ko", "es"], "default": "en", "description": "language of the reading"}}, "required": ["dna_ids"]}}}}}}, "/api/dna/{dna_id}/playbook": {"post": {"operationId": "build_playbook", "summary": "Write the brand playbook", "description": "Write (or rewrite) the brand playbook and AI skills for an existing Brand DNA: constitution, audience, voice, visual rules, one playbook per format (banner, shorts, video ad, brand film, brand content, blog, PR article, social post), examples, self-check, prompts and a sonic logo. Owner only; included in every new run. Changes saved data in the app; no credits.", "tags": ["action"], "x-lm-kind": "action", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "dna_id", "in": "path", "required": true, "description": "Brand DNA id", "schema": {"type": "string"}}]}}, "/api/dna/{dna_id}/brief": {"get": {"operationId": "get_brand_brief", "summary": "Brand brief for agents", "description": "Start here before writing anything for the brand: a compact brief (purpose, customer words, market entry points with search volume, voice, colours, fonts, film patterns, big idea, priorities, exact rules), each fact with its evidence grade. Read only, free.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "dna_id", "in": "path", "required": true, "description": "Brand DNA id (from list_dna or get_run)", "schema": {"type": "string"}}]}}, "/api/dna/{dna_id}/format/{format}": {"get": {"operationId": "get_format_guide", "summary": "Format guide", "description": "One format's playbook with voice essentials, the customer's words, colours, the self-check and length limits. Read only, free.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "dna_id", "in": "path", "required": true, "description": "Brand DNA id (from list_dna or get_run)", "schema": {"type": "string"}}, {"name": "format", "in": "path", "required": true, "description": "Content format", "schema": {"type": "string", "enum": ["banner", "shorts", "video_ad", "brand_film", "brand_content", "blog", "pr_article", "social_post"]}}]}}, "/api/dna/{dna_id}/review": {"post": {"operationId": "review_content", "summary": "Review a draft", "description": "Check a draft against the brand before handing it over: exact checks (avoid words, brand vocabulary, length) and judged checks (rules, voice, checklist) with a score, fixes and a rewrite. Changes saved data in the app; no credits.", "tags": ["action"], "x-lm-kind": "action", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "dna_id", "in": "path", "required": true, "description": "Brand DNA id (from list_dna or get_run)", "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"text": {"type": "string", "description": "The draft: copy, script, article, post or prompt"}, "format": {"type": "string", "description": "Content format, optional"}}, "required": ["text"]}}}}}}, "/api/dna/{dna_id}/kit": {"get": {"operationId": "get_brand_kit", "summary": "Brand kit links", "description": "Download links: Claude skill, ChatGPT GPT, Gemini gem, everything (with the report as HTML, PDF and JSON), the raea project and rendered drafts. Read only, free.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "dna_id", "in": "path", "required": true, "description": "Brand DNA id (from list_dna or get_run)", "schema": {"type": "string"}}]}}}, "externalDocs": {"url": "https://brand-dna.listeningmind.ai/agents.md", "description": "Agent guide"}}