{"openapi": "3.1.0", "info": {"title": "Creative Finder API", "version": "1.0.0", "description": "Give one to three product lines. The app finds the moments when people think of them in ListeningMind DaaS data (related searches, real search paths, monthly volume), grades the evidence in code, and writes a 15-second creative draft with a distinct tone per moment. Images and 8-second vertical videos can be generated per draft. Markets KR, JP, US; UI ko, en, ja. Workflow: assist_brief → check_keywords → estimate_run → start_run → get_run_status → get_run → generate_image → generate_video → list_assets → get_report_html", "contact": {"email": "m-support@listeningmind.com"}}, "servers": [{"url": "https://daas-creative.listeningmind.ai"}], "paths": {"/api/assist/brief": {"post": {"operationId": "assist_brief", "summary": "Brief assistant", "description": "Measures one keyword, pulls its related searches and proposes product lines (with volume), regulatory domain, audience, channel, principles and fixed elements. Returns credits spent. About 500 Data API credits, 10-20 seconds. 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: about 500 credits. Usually followed by: estimate_run, start_run.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 500 credits", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"keyword": {"type": "string", "description": "one product or category name"}, "gl": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr", "description": "market: kr, jp or us"}, "lang": {"type": "string", "enum": ["ko", "en", "ja"], "default": "ko", "description": "language of the answer and the drafts: ko, en or ja"}, "brand_notes": {"type": "string", "description": "free text about the brand or campaign"}}, "required": ["keyword"]}}}}}}, "/api/assist/keywords": {"post": {"operationId": "check_keywords", "summary": "Check keyword volume", "description": "Returns monthly search volume for up to 3 hand-typed product line keywords. 1 credit per keyword. 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: about 1-3 credits (1 per keyword).", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 1-3 credits (1 per keyword)", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"keywords": {"type": "array", "items": {"type": "string"}, "description": "product line keywords to measure (search volume and trend)"}, "gl": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr", "description": "market: kr, jp or us"}}, "required": ["keywords"]}}}}}}, "/api/estimate": {"post": {"operationId": "estimate_run", "summary": "Estimate", "description": "Estimated credits for a run with these lines and depth, plus Lima. 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": {"lines": {"type": "array", "items": {"type": "string"}, "description": "1-3 product line keywords that have search volume"}, "depth": {"type": "string", "enum": ["quick", "standard", "deep"], "default": "standard", "description": "quick, standard or deep (see start_run)"}, "gl": {"type": "string", "default": "kr", "description": "market: kr, jp or us"}}, "required": ["lines"]}}}}}}, "/api/runs": {"post": {"operationId": "start_run", "summary": "Start run", "description": "Starts the full pipeline in the background and returns run_id and estimate_credits. standard depth takes 5-10 minutes and about 35,000-45,000 Data API credits plus a small LLM cost. 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: about 35,000-45,000 credits (standard). Time: 5-10 minutes. Usually followed by: get_run_status.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 35,000-45,000 credits (standard)", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"lines": {"type": "array", "items": {"type": "string"}, "description": "1-3 product line keywords with search volume"}, "gl": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr", "description": "market: kr, jp or us"}, "lang": {"type": "string", "enum": ["ko", "en", "ja"], "default": "ko", "description": "language of the answer and the drafts: ko, en or ja"}, "depth": {"type": "string", "enum": ["quick", "standard", "deep"], "default": "standard", "description": "quick: related searches only; standard: one path per line plus 4 situation paths; deep: 10 situation paths"}, "title": {"type": "string", "description": "run title shown in the list"}, "audience": {"type": "string", "description": "who the ads are for, in plain words"}, "channel": {"type": "string", "enum": ["meta_reels", "meta_carousel", "youtube_shorts", "display"], "default": "meta_reels", "description": "meta_reels, meta_carousel, youtube_shorts or display"}, "reg_domain": {"type": "string", "enum": ["hfs", "food", "cosmetic", "quasidrug", "device", "finance", "general"], "default": "general", "description": "regulatory domain for the wording check: hfs, food, cosmetic, quasidrug, device, finance or general"}, "principles": {"type": "array", "items": {"type": "string"}, "description": "wording principles the drafts must keep"}, "exclude_topics": {"type": "array", "items": {"type": "string"}, "description": "topics the drafts must not touch"}, "fixed_elements": {"type": "string", "description": "elements every draft must keep, such as the product name, a claim or a closing line"}, "creatives_per_line": {"type": "integer", "minimum": 0, "maximum": 6, "default": 0, "description": "0 = depth default (3 quick, 5 standard/deep)"}}, "required": ["lines"]}}}}}, "get": {"operationId": "list_runs", "summary": "List runs", "description": "Runs of the signed-in member (all runs for staff), 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 runs to list, newest first", "schema": {"type": "integer", "default": 100}}]}}, "/api/runs/{run_id}/status": {"get": {"operationId": "get_run_status", "summary": "Run status", "description": "Status, stage, percent and credits spent so far. Repeat until status is done or error. Read only, free. Waits up to about 45 s for 'status' to reach done, error; call again if not done. 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 returned by start_run", "schema": {"type": "string"}}]}}, "/api/runs/{run_id}": {"get": {"operationId": "get_run", "summary": "Get run", "description": "Full result JSON of a finished run (lines, market, ceps, matrix, creatives, notes, credits) plus generated assets. Read only, free. Usually followed by: generate_image, generate_video, get_report_html.", "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 returned by start_run", "schema": {"type": "string"}}]}, "delete": {"operationId": "delete_run", "summary": "Delete run", "description": "Deletes a run and its asset rows (owner or staff only). 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 returned by start_run", "schema": {"type": "string"}}]}}, "/api/runs/{run_id}/creatives/{creative_id}/regenerate": {"post": {"operationId": "regenerate_creative", "summary": "Rewrite a creative", "description": "Rewrites one creative draft with the person's instructions (new tone allowed). Small LLM cost, reported in credits. 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: about 10-30 credits.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 10-30 credits", "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 returned by start_run", "schema": {"type": "string"}}, {"name": "creative_id", "in": "path", "required": true, "description": "C1, C2, ...", "schema": {"type": "string"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"instructions": {"type": "string", "description": "what to change in the draft, in plain words"}}, "required": []}}}}}}, "/api/runs/{run_id}/creatives/{creative_id}/image": {"post": {"operationId": "generate_image", "summary": "Image draft", "description": "Starts image generation for one creative in the background (Gemini image or OpenAI image). Returns the asset row; poll list_assets until status is done. About 40-130 credits per image. 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: about 40-130 credits. Time: 10-40 seconds. Usually followed by: list_assets.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 40-130 credits", "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 returned by start_run", "schema": {"type": "string"}}, {"name": "creative_id", "in": "path", "required": true, "description": "creative draft id in the run: C1, C2, ...", "schema": {"type": "string"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"provider": {"type": "string", "enum": ["gemini", "openai"], "default": "gemini", "description": "image or video model family: gemini or openai"}, "quality": {"type": "string", "enum": ["fast", "hq"], "default": "fast", "description": "fast or hq for images; fast or lite for videos"}, "prompt": {"type": "string", "description": "optional override of the stored image prompt"}}, "required": []}}}}}}, "/api/runs/{run_id}/creatives/{creative_id}/video": {"post": {"operationId": "generate_video", "summary": "Video draft", "description": "Starts an 8-second vertical video for one creative (Veo 3.1 fast/lite or Sora 2). Poll list_assets until done. About 400-1,200 credits per clip. 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: about 400-1,200 credits. Time: 1-3 minutes. Usually followed by: list_assets.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 400-1,200 credits", "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 returned by start_run", "schema": {"type": "string"}}, {"name": "creative_id", "in": "path", "required": true, "description": "creative draft id in the run: C1, C2, ...", "schema": {"type": "string"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"provider": {"type": "string", "enum": ["gemini", "openai"], "default": "gemini", "description": "image or video model family: gemini or openai"}, "quality": {"type": "string", "enum": ["fast", "lite"], "default": "fast", "description": "fast or hq for images; fast or lite for videos"}, "prompt": {"type": "string", "description": "optional override of the stored prompt (no text in the picture)"}, "seconds": {"type": "integer", "minimum": 4, "maximum": 8, "default": 8, "description": "video length in seconds, 4 to 8"}}, "required": []}}}}}}, "/api/runs/{run_id}/media/batch": {"post": {"operationId": "generate_media_batch", "summary": "Batch media", "description": "Starts images or videos for every creative that has none yet. Returns started asset ids and the estimate. 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: about 40-130 credits per image, about 400-1,200 per video.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 40-130 credits per image, about 400-1,200 per video", "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 returned by start_run", "schema": {"type": "string"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["image", "video"], "default": "image", "description": "image or video"}, "provider": {"type": "string", "enum": ["gemini", "openai"], "default": "gemini", "description": "image or video model family: gemini or openai"}, "quality": {"type": "string", "default": "fast", "description": "fast or hq for images; fast or lite for videos"}, "creative_ids": {"type": "array", "items": {"type": "string"}, "description": "draft ids to generate for; all drafts without media when empty"}}, "required": []}}}}}}, "/api/runs/{run_id}/assets": {"get": {"operationId": "list_assets", "summary": "Assets", "description": "All generated images and videos of a run with status, file name and credits. Files are served at /api/runs/{run_id}/assets/{file}. Read only, free. Waits up to about 45 s for 'assets[].status' to reach done, error; call again if not done.", "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 returned by start_run", "schema": {"type": "string"}}]}}, "/api/runs/{run_id}/report.html": {"get": {"operationId": "get_report_html", "summary": "Report HTML", "description": "Standalone HTML report of a finished run (sections A to F and appendix). embed=1 inlines generated images. 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": "run_id", "in": "path", "required": true, "description": "run id returned by start_run", "schema": {"type": "string"}}, {"name": "embed", "in": "query", "required": false, "description": "1 returns the report without the page shell, for embedding", "schema": {"type": "integer", "default": 0}}]}}, "/api/runs/{run_id}/brief.md": {"get": {"operationId": "get_brief_md", "summary": "Brief markdown", "description": "Markdown brief of a finished run. 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": "run_id", "in": "path", "required": true, "description": "run id returned by start_run", "schema": {"type": "string"}}]}}, "/api/runs/{run_id}/run.json": {"get": {"operationId": "get_run_json", "summary": "Run JSON", "description": "Downloadable JSON of the result and assets. 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": "run_id", "in": "path", "required": true, "description": "run id returned by start_run", "schema": {"type": "string"}}]}}}, "externalDocs": {"url": "https://daas-creative.listeningmind.ai/agents.md", "description": "Agent guide"}}