{"openapi": "3.1.0", "info": {"title": "Intent KG API", "version": "1.0.0", "description": "Give a topic and it builds a graph of intent elements (entry situations, choice criteria, brands, pitfalls, thresholds and more) and their relations, with evidence grades, from ListeningMind search data (related searches, clusters, search journeys, SERPs and AI Overviews). Used by marketers, product planners and AI agents that need grounded answers. Stored graphs are reused at 0 credits through the v1 and v2 APIs and 21 export formats. Markets: Korea, Japan, US. Workflow: lookup_topic → check_launch → resolve_topic → start_build → get_job → get_ontology_digest → get_decision_pack → get_question_pack → get_dossier_md → export_run → compare_runs → plan_rerun → rerun_build", "contact": {"email": "m-support@listeningmind.com"}}, "servers": [{"url": "https://daas-intent.listeningmind.ai"}], "paths": {"/api/v1/lookup": {"get": {"operationId": "lookup_or_build_topic", "summary": "Look up or build (v1)", "description": "Same as lookup_topic, but when no stored run matches it starts a build (joins a running build of the same topic if one exists). With wait=0 it returns job_id at once; with wait up to 600 seconds it waits and returns the digest if the build finishes. Spends about 35,000-37,000 Data API credits when a build starts; ask the person first. The server may disable builds through this API (reason build_disabled). 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: 0 if a stored run matches, otherwise about 35,000-37,000 Data API credits plus LLM calls. Time: 2-6 minutes when it builds. Usually followed by: get_job.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "0 if a stored run matches, otherwise about 35,000-37,000 Data API credits plus LLM calls", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "topic", "in": "query", "required": true, "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'.", "schema": {"type": "string"}}, {"name": "gl", "in": "query", "required": false, "description": "Market: kr (Korea), jp (Japan), us (United States).", "schema": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr"}}, {"name": "types", "in": "query", "required": false, "description": "Optional comma-separated node types to keep, e.g. 'cep,kbf,pitfall'. Types: cep, occasion, nano_intent, kbf, constraint, threshold, avoidance, rtb, heuristic, convention, expectation, pitfall, tradeoff, benchmark, stance, topic, category, entity, brand, product, attribute, audience, channel, alternative, content.", "schema": {"type": "string"}}, {"name": "build", "in": "query", "required": true, "description": "Must be 1: build when no stored run matches.", "schema": {"type": "integer", "enum": [1], "default": 1}}, {"name": "wait", "in": "query", "required": false, "description": "Seconds to wait for the build. 0 returns job_id immediately; poll get_job.", "schema": {"type": "integer", "minimum": 0, "maximum": 600, "default": 0}}]}}, "/api/launch_check": {"get": {"operationId": "check_launch", "summary": "Pre-build check", "description": "Before building a topic, returns finished runs of the same topic and market (up to 5, reuse them instead of rebuilding), whether a parent run's clusters can be reused for a cheaper child run, a scope verdict for the child topic, and credit estimates for a child run and a standalone standard run. Starts nothing. Read only, free. Cost: free (reads stored runs, 0 credits). Usually followed by: resolve_topic, start_build.", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 credits)", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "parameters": [{"name": "topic", "in": "query", "required": true, "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'.", "schema": {"type": "string"}}, {"name": "gl", "in": "query", "required": false, "description": "Market: kr (Korea), jp (Japan), us (United States).", "schema": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr"}}, {"name": "parent_run", "in": "query", "required": false, "description": "Optional finished run whose clusters a child run would reuse (must be same gl).", "schema": {"type": "string"}}, {"name": "scale", "in": "query", "required": false, "description": "Optional scale preset for the estimate. Default standard.", "schema": {"type": "string", "enum": ["standard", "extended"]}}]}}, "/api/resolve": {"post": {"operationId": "resolve_topic", "summary": "Resolve meaning", "description": "Stage 0: decides what the topic word means before collecting data. Returns query, ambiguous (true when several meanings are plausible) and candidates, each with id, label and seeds. If ambiguous, let the person pick a candidate, then pass sense_id, seeds and the whole result as resolution to start_build. Results are cached per topic and market for 15 minutes. One LLM call, no Data API 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: one LLM call, no Data API credits (cached 15 minutes). Time: about 5-30 seconds. Usually followed by: start_build.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "one LLM call, no Data API credits (cached 15 minutes)", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"topic": {"type": "string", "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'."}, "gl": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr", "description": "Market: kr (Korea), jp (Japan), us (United States)."}}, "required": ["topic"]}}}}}}, "/api/seed_plan": {"post": {"operationId": "create_seed_plan", "summary": "Create seed plan", "description": "Optional alternative to resolve_topic: widens the input into real nearby search terms using cheap lookups (two related-keyword lists plus keyword info) and proposes seeds and a journey allocation with a cost estimate. Does not build. Returns a plan with id, seeds, allocation and credits; pass the id as seed_plan_id (optionally with edited seeds) to start_build. 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: up to about 3,000 Data API credits (reserved), plus one LLM call if the meaning is not cached. Time: about 20-60 seconds. Usually followed by: get_seed_plan, start_build.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "up to about 3,000 Data API credits (reserved), plus one LLM call if the meaning is not cached", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"topic": {"type": "string", "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'."}, "gl": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr", "description": "Market: kr (Korea), jp (Japan), us (United States)."}, "seeds": {"type": "array", "items": {"type": "string"}, "description": "Optional seeds the person wants included."}}, "required": ["topic"]}}}}}}, "/api/seed_plan/{plan_id}": {"get": {"operationId": "get_seed_plan", "summary": "Get seed plan", "description": "Returns a saved seed plan by id (topic, gl, seeds, allocation, credit estimate). 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": "plan_id", "in": "path", "required": true, "description": "Seed plan id (12 hex chars) from create_seed_plan.", "schema": {"type": "string"}}]}}, "/api/build": {"post": {"operationId": "start_build", "summary": "Build intent graph", "description": "Builds an Intent Knowledge Graph for a topic: resolves the meaning, collects related searches, clusters, search journeys and SERPs/AI Overviews, then extracts typed nodes (CEP, KBF, brands, pitfalls, thresholds and more) and relations with evidence grades. Returns job_id. If the same topic and market is already building it returns that job with joined=true; if a standard run of the same topic finished within about 20 hours it returns that run with reused=true at 0 credits (set force=true for a new snapshot). Ask the person before calling. 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-37,000 Data API credits for standard (recent median about 37,000), more for extended, less for a child run; 0 when an earlier run is reused; plus LLM calls. Time: 2-6 minutes (up to about 9). Usually followed by: get_job.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 35,000-37,000 Data API credits for standard (recent median about 37,000), more for extended, less for a child run; 0 when an earlier run is reused; plus LLM calls", "responses": {"200": {"description": "Success"}, "default": {"description": "Error (application/problem+json or JSON with detail)"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"topic": {"type": "string", "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'."}, "gl": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr", "description": "Market: kr (Korea), jp (Japan), us (United States)."}, "sense_id": {"type": "string", "description": "Optional chosen candidate id from resolve_topic. Fixes the meaning so data is collected for that sense only. With a seed plan the server sets it to seed_plan."}, "seeds": {"type": "array", "items": {"type": "string"}, "description": "Optional seed keywords, editable by the person (the UI shows them comma-separated in the meaning and seed-plan dialogs). The first seeds drive cluster and journey lookups, which are about 90% of the cost. Omitted: seeds come from the meaning step. Giving seeds turns off same-day reuse."}, "resolution": {"type": "object", "description": "Optional full resolve_topic result, passed back as the UI does."}, "force": {"type": "boolean", "default": false, "description": "true skips joining a running build and same-day reuse and always builds a new snapshot (the UI 'make a new snapshot' button)."}, "scale": {"type": "string", "enum": ["standard", "extended"], "default": "standard", "description": "Collection size preset. standard uses the server defaults (currently seeds 6, SERP bodies 40, keyword universe 200). extended sets seed_query_limit 9, serp_max_keywords 60, max_keywords 320: more evidence and nodes, more credits (about 2,000 per extra seed). deep exists on the server but is refused."}, "overrides": {"type": "object", "additionalProperties": false, "description": "Optional per-run settings applied on top of the scale preset (API only, not in the UI). Any other key is rejected with HTTP 400. Giving any override turns off same-day reuse.", "properties": {"seed_query_limit": {"type": "integer", "minimum": 1, "description": "Seeds actually queried for related searches. Live default 6 (extended 9). About 2,000 credits per extra seed; more seeds widen the keyword universe."}, "serp_max_keywords": {"type": "integer", "minimum": 0, "description": "Top keywords whose SERP and AI Overview bodies are collected. Live default 40 (extended 60). About 10 credits each; the knowledge layer (pitfalls, conventions, thresholds) comes from these bodies."}, "max_keywords": {"type": "integer", "minimum": 1, "description": "Ceiling of the keyword universe. Live default 200 (extended 320). About 10 credits per extra keyword."}, "metrics_max_keywords": {"type": "integer", "minimum": 0, "description": "Keywords measured with keyword info (volume, intent, competition). Code default 120 (live value not exposed)."}, "cluster_seed_limit": {"type": "integer", "minimum": 1, "description": "Seeds sent to cluster_finder. Code default 1; each call costs about 13,850 credits. Raising it gives more cluster structure. Child runs (parent_run) force it to 1 and reuse the parent's clusters."}, "journey_seed_limit": {"type": "integer", "minimum": 0, "description": "Seeds whose search journeys (path_finder) are collected. Code default 2; journeys feed the journey analysis and relation evidence."}, "anchor_prev": {"type": "boolean", "description": "Default true: reuse node names from the previous run of the same topic so node keys stay comparable across runs. false lets names drift."}}}, "parent_run": {"type": "string", "description": "Optional finished run (same gl) whose clusters are reused for a child topic; saves about 13,850 credits."}, "parent_node": {"type": "string", "description": "Optional node id in the parent run that this child topic expands."}, "parent_node_label": {"type": "string", "description": "Optional label of that parent node."}, "seed_plan_id": {"type": "string", "description": "Optional seed plan id from create_seed_plan; topic and gl must match the plan."}}, "required": ["topic"]}}}}}}, "/api/jobs/{run_id}": {"get": {"operationId": "get_job", "summary": "Build status", "description": "Returns a build's status (queued, running, done, error), progress log entries (stage, pct, msg, extra), error, duration, config, sense, seeds, stats and readiness. Repeat until status is done or error, then read the graph with get_result, get_tree or get_ontology_digest. Read only, free. Waits up to about 45 s for 'status' to reach done, error; call again if not done. Usually followed by: get_result, get_ontology_digest.", "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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/jobs/{run_id}/result": {"get": {"operationId": "get_result", "summary": "Full result", "description": "Returns the pipeline result of a run: ontology (nodes, edges, limits, readiness, spec check, journey verdicts), keywords, sense, seeds and stats. slim=1 drops the bulky serp, clusters, journeys and keyword detail; use it unless you need raw evidence. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "slim", "in": "query", "required": false, "description": "1 returns a slim result without SERP bodies, clusters and journeys.", "schema": {"type": "integer", "enum": [0, 1], "default": 0}}]}}, "/api/v1/ontology/{run_id}": {"get": {"operationId": "get_ontology_digest", "summary": "Graph digest (v1)", "description": "Returns a specific run in the stable v1 format. view=digest gives the same digest as lookup_topic (grouped nodes, relations, readiness, limits, journey summary); view=full returns the whole ontology graph. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "view", "in": "query", "required": false, "description": "digest or full graph.", "schema": {"type": "string", "enum": ["digest", "full"], "default": "digest"}}, {"name": "types", "in": "query", "required": false, "description": "Optional comma-separated node types to keep, e.g. 'cep,kbf,pitfall'. Types: cep, occasion, nano_intent, kbf, constraint, threshold, avoidance, rtb, heuristic, convention, expectation, pitfall, tradeoff, benchmark, stance, topic, category, entity, brand, product, attribute, audience, channel, alternative, content.", "schema": {"type": "string"}}]}}, "/api/jobs/{run_id}/tree": {"get": {"operationId": "get_tree", "summary": "Tree view", "description": "Returns the graph as a hierarchy rooted at the topic (the tree tab of the page). Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/jobs/{run_id}/journeys": {"get": {"operationId": "get_journeys", "summary": "Search journey analysis", "description": "Returns the search journey analysis computed from the run's stored path_finder data: where searches flow before and after the topic, alternatives weighed, and verifiability. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/v2/decision-packs/{run_id}": {"get": {"operationId": "get_decision_pack", "summary": "Decision pack (v2)", "description": "Returns a decision evidence pack for a finished run: nodes and edges with evidence, a gate verdict, limits, sources and verification tasks, shaped for a purpose. Use it when an agent must decide what it can safely claim. 404 if the run does not exist, 409 if not completed, 410 if archived. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "purpose", "in": "query", "required": false, "description": "exploration, content_brief, or product_claim (strictest evidence rules).", "schema": {"type": "string", "enum": ["exploration", "content_brief", "product_claim"], "default": "exploration"}}]}}, "/api/v2/question-packs/{run_id}": {"get": {"operationId": "get_question_pack", "summary": "Question pack (v2)", "description": "For one real customer question, splits what the run can answer: conditions it can answer, weak ones, missing product evidence and content to improve. Give conditions explicitly when possible; otherwise they are split from the question and the gate may say NO_CONDITIONS. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "q", "in": "query", "required": true, "description": "The customer question, 2-300 characters.", "schema": {"type": "string", "minLength": 2, "maxLength": 300}}, {"name": "conditions", "in": "query", "required": false, "description": "Optional conditions, comma-separated; aliases joined with '|', e.g. '세척 용이|세척,밀폐|누수'.", "schema": {"type": "string", "maxLength": 600}}]}}, "/api/jobs/{run_id}/dossier.md": {"get": {"operationId": "get_dossier_md", "summary": "Node dossier (Markdown)", "description": "Returns a readable dossier of the run in Markdown: each tree node explained with evidence, journeys and approved concepts. Best text version of a run page for an agent. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "scope", "in": "query", "required": false, "description": "Which nodes to include: all; measured (measured or quote-verified nodes only); knowledge (conventions, pitfalls, benchmarks and other claims); decision (entry situations, solutions, choice criteria, thresholds).", "schema": {"type": "string", "enum": ["all", "measured", "knowledge", "decision"], "default": "all"}}]}}, "/api/jobs/{run_id}/dossier.html": {"get": {"operationId": "get_dossier_html", "summary": "Dossier (HTML)", "description": "Returns the same dossier as an HTML page. By default it is laid out for printing; print=1 gives the screen layout. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "scope", "in": "query", "required": false, "description": "Which nodes to include: all; measured (measured or quote-verified nodes only); knowledge (conventions, pitfalls, benchmarks and other claims); decision (entry situations, solutions, choice criteria, thresholds).", "schema": {"type": "string", "enum": ["all", "measured", "knowledge", "decision"], "default": "all"}}, {"name": "print", "in": "query", "required": false, "description": "0 print layout (default), 1 screen layout.", "schema": {"type": "integer", "enum": [0, 1], "default": 0}}]}}, "/api/jobs/{run_id}/dossier.pdf": {"get": {"operationId": "download_dossier_pdf", "summary": "Dossier PDF", "description": "Renders the dossier to PDF with headless Chromium and returns the file. Can take up to a few minutes for large runs. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "scope", "in": "query", "required": false, "description": "Which nodes to include: all; measured (measured or quote-verified nodes only); knowledge (conventions, pitfalls, benchmarks and other claims); decision (entry situations, solutions, choice criteria, thresholds).", "schema": {"type": "string", "enum": ["all", "measured", "knowledge", "decision"], "default": "all"}}]}}, "/api/jobs/{run_id}/export.{fmt}": {"get": {"operationId": "export_run", "summary": "Export", "description": "Downloads the run's graph in one of 21 formats: json (full original), agentpack (compact conclusions, evidence and limits for agents), claims (JSONL claims with sources), jsonld, ttl, rdfxml, nt, trig, nq, owl, skos, tbox (schema), shacl (shapes), graphml, gexf, dot, neo4j (zip of CSVs), csv (triples), xlsx, md (mindmap), bundle (zip). Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "fmt", "in": "path", "required": true, "description": "Export format.", "schema": {"type": "string", "enum": ["json", "agentpack", "claims", "jsonld", "ttl", "rdfxml", "nt", "trig", "nq", "owl", "skos", "tbox", "shacl", "graphml", "gexf", "dot", "neo4j", "csv", "xlsx", "md", "bundle"]}}]}}, "/api/jobs/{run_id}/export_audit": {"get": {"operationId": "get_export_audit", "summary": "Export coverage audit", "description": "For each export format, measures what is kept or lost (labels, definitions, quotes, volumes, sources, edges) by checking the actual exported files. Use it to pick a format. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/jobs/{run_id}/bundle.html": {"get": {"operationId": "download_bundle", "summary": "Single-file HTML bundle", "description": "Returns one self-contained HTML file with all tabs and data of the run that opens in a browser without the server (read-only). Use it to share a run outside the internal network. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/jobs/{run_id}/health": {"get": {"operationId": "get_run_health", "summary": "Pipeline health", "description": "Scores where in the pipeline this run became thin (per-node checks and first attribution), using thresholds the pipeline already uses. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/jobs/{run_id}/shacl": {"get": {"operationId": "get_shacl_report", "summary": "SHACL validation", "description": "Validates the run's data graph against the SHACL shape graph (pyshacl, no inference) and returns the conformance result, violations and links to the shapes file. Read only, free. Cost: free (reads stored runs, 0 credits).", "tags": ["read"], "x-lm-kind": "read", "x-lm-cost": "free (reads stored runs, 0 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "Maximum violations to list.", "schema": {"type": "integer", "minimum": 1, "maximum": 2000, "default": 300}}]}}, "/api/schema/spec.shacl.ttl": {"get": {"operationId": "get_shacl_spec", "summary": "SHACL spec file", "description": "Returns the SHACL shapes (Turtle) that define valid relations, evidence and entailment rules for all runs. 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)"}}}}, "/api/v1/schema": {"get": {"operationId": "get_schema", "summary": "Type schema (v1)", "description": "Describes the vocabulary: node types and layers, relations and their signatures, evidence grades, adjudication rules and fingerprints. Read it once to understand node types before using the graph. 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)"}}}}, "/api/jobs/{run_id}/conform": {"post": {"operationId": "apply_conform", "summary": "Apply spec conformance fix", "description": "Applies the current conformance rules to a stored run and saves it; each changed relation keeps its original direction and name in provenance and a note is added to limits. No credits. Requires write access. 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": "run_id", "in": "path", "required": true, "description": "Run id (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}, {"name": "apply", "in": "query", "required": true, "description": "Must be true to save the changes.", "schema": {"type": "boolean", "enum": [true], "default": true}}]}}, "/api/explain": {"post": {"operationId": "explain_highlight", "summary": "Explain a highlight", "description": "Asks the model to explain one highlight of the graph using only the facts you send (why it matters, structure, market, marketing and product implications, caveat). The model may not add numbers or brands not in facts. Results are cached per run, title and facts. 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: one LLM call, no Data API credits. Time: about 5-30 seconds.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "one LLM call, no Data API 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": {"run_id": {"type": "string", "description": "Run id (12 hex chars). The job id returned by start_build is the same id."}, "title": {"type": "string", "description": "Title of the highlight."}, "rule": {"type": "string", "default": "", "description": "Rule that selected this highlight."}, "facts": {"type": "array", "items": {"type": "string"}, "default": [], "description": "Fact lines with numbers (volume, journey counts, quote checks). At most 80 are used, 400 characters each."}, "topic": {"type": "string", "default": "", "description": "Topic of the run."}}, "required": ["run_id", "title"]}}}}}}, "/api/reviews": {"get": {"operationId": "list_reviews", "summary": "Review queue", "description": "With run_id: nodes of that run that need human review, with features, predicted approval and any AI suggestion. Without run_id: all review decisions so far and stats. Read only, free. Usually followed by: set_review, ai_suggest_reviews.", "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": "query", "required": false, "description": "Optional run id.", "schema": {"type": "string"}}]}, "post": {"operationId": "set_review", "summary": "Save review decision", "description": "Saves a human review decision for one node key. Requires write access; the reviewer is recorded from the token or network plus the optional name. 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": {"key": {"type": "string", "description": "Review item key from list_reviews."}, "status": {"type": "string", "enum": ["pending", "approved", "rejected", "needs_edit"], "description": "Decision."}, "reviewer": {"type": "string", "default": "", "description": "Optional reviewer name."}, "note": {"type": "string", "default": "", "description": "Optional note."}, "label": {"type": "string", "default": "", "description": "Node label."}, "type": {"type": "string", "default": "", "description": "Node type."}, "topic": {"type": "string", "default": "", "description": "Run topic."}, "run_id": {"type": "string", "default": "", "description": "Run id the item came from."}}, "required": ["key", "status"]}}}}}}, "/api/reviews/ai_suggest": {"post": {"operationId": "ai_suggest_reviews", "summary": "AI pre-review", "description": "Runs AI suggestions (approved, rejected, needs_edit) for all review items of a run, in batches of 25 per LLM call. Suggestions are advisory and shown next to items in list_reviews. Requires write access. 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: several LLM calls (one per 25 items), no Data API credits.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "several LLM calls (one per 25 items), no Data API 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": {"run_id": {"type": "string", "description": "Run id (12 hex chars). The job id returned by start_build is the same id."}}, "required": ["run_id"]}}}}}}, "/api/concepts": {"get": {"operationId": "list_concepts", "summary": "Concept candidates", "description": "Lists concept candidates for a topic (nodes reproduced across runs of the same topic) and their approval status. Read only, free. Usually followed by: set_concept.", "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": "topic", "in": "query", "required": true, "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'.", "schema": {"type": "string"}}, {"name": "gl", "in": "query", "required": false, "description": "Market: kr (Korea), jp (Japan), us (United States).", "schema": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr"}}, {"name": "limit", "in": "query", "required": false, "description": "How many recent runs to overlay.", "schema": {"type": "integer", "minimum": 1, "maximum": 12, "default": 6}}]}, "post": {"operationId": "set_concept", "summary": "Verify or retire concept", "description": "Approves (verify) a reproduced node as a stable concept with an id, or retires an approved concept. Only keys listed by list_concepts can be verified. Requires write access. 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": {"topic": {"type": "string", "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'."}, "gl": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr", "description": "Market: kr (Korea), jp (Japan), us (United States)."}, "key": {"type": "string", "description": "Candidate key from list_concepts."}, "action": {"type": "string", "enum": ["verify", "retire"], "description": "verify or retire."}, "reviewer": {"type": "string", "description": "Optional reviewer name."}, "label": {"type": "string", "description": "Optional concept label."}, "aliases": {"type": "array", "items": {"type": "string"}, "description": "Optional aliases."}, "definition": {"type": "string", "description": "Optional definition."}, "note": {"type": "string", "description": "Optional note, e.g. retire reason."}}, "required": ["topic", "key", "action"]}}}}}}, "/api/jobs/{run_id}/concepts": {"get": {"operationId": "get_run_concepts", "summary": "Concepts in run", "description": "Returns which nodes of this run map to approved concepts ({node_id: concept_id, label, version, due}). 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/consensus": {"get": {"operationId": "get_consensus", "summary": "Consensus graph", "description": "Overlays recent runs of the same topic and returns how often each node and relation appears and how stable it is; nodes reproduced in at least k of n runs are marked entailed. 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": "topic", "in": "query", "required": true, "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'.", "schema": {"type": "string"}}, {"name": "gl", "in": "query", "required": false, "description": "Market: kr (Korea), jp (Japan), us (United States).", "schema": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr"}}, {"name": "limit", "in": "query", "required": false, "description": "How many recent runs to overlay.", "schema": {"type": "integer", "minimum": 2, "maximum": 12, "default": 6}}, {"name": "k", "in": "query", "required": false, "description": "Optional minimum repeats for entailed.", "schema": {"type": "integer", "minimum": 2, "maximum": 12}}, {"name": "family", "in": "query", "required": false, "description": "Also include child-topic runs whose parent is this topic.", "schema": {"type": "boolean", "default": true}}, {"name": "topics", "in": "query", "required": false, "description": "Optional extra topics, comma-separated, of the same category to overlay.", "schema": {"type": "string"}}]}}, "/api/topics": {"get": {"operationId": "list_topics", "summary": "Topics with runs", "description": "Lists topics that have finished runs, to choose topics for a combined graph. 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": "gl", "in": "query", "required": false, "description": "Optional market filter: kr, jp or us.", "schema": {"type": "string", "enum": ["kr", "jp", "us"]}}]}}, "/api/topics/related": {"get": {"operationId": "get_related_topics", "summary": "Related topics", "description": "Returns other topics that share identity keys with this topic, with the shared concepts as evidence. 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": "topic", "in": "query", "required": true, "description": "Topic word as people search it, e.g. '호텔', 'electric toothbrush'.", "schema": {"type": "string"}}, {"name": "gl", "in": "query", "required": false, "description": "Market: kr (Korea), jp (Japan), us (United States).", "schema": {"type": "string", "enum": ["kr", "jp", "us"], "default": "kr"}}, {"name": "limit", "in": "query", "required": false, "description": "Maximum topics.", "schema": {"type": "integer", "minimum": 1, "maximum": 30, "default": 10}}]}}, "/api/xindex": {"get": {"operationId": "search_nodes", "summary": "Search nodes across runs", "description": "Searches nodes across all runs by text (cross-run index), optionally filtered by node type. 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": "q", "in": "query", "required": true, "description": "Search text.", "schema": {"type": "string"}}, {"name": "types", "in": "query", "required": false, "description": "Optional comma-separated node types to keep, e.g. 'cep,kbf,pitfall'. Types: cep, occasion, nano_intent, kbf, constraint, threshold, avoidance, rtb, heuristic, convention, expectation, pitfall, tradeoff, benchmark, stance, topic, category, entity, brand, product, attribute, audience, channel, alternative, content.", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "Maximum results.", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 60}}]}}, "/api/xindex/contradictions": {"get": {"operationId": "list_contradictions", "summary": "Numeric contradictions", "description": "Lists pairs of claims from different runs with similar content but different numbers. 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": "Maximum pairs.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 40}}]}}, "/api/runs": {"get": {"operationId": "list_runs", "summary": "Run history", "description": "Lists saved runs newest first (id, topic, gl, status, created, finished, duration, counts, config) plus store stats. Use topic to filter. 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": "Rows to return.", "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100}}, {"name": "offset", "in": "query", "required": false, "description": "Rows to skip.", "schema": {"type": "integer", "minimum": 0, "default": 0}}, {"name": "topic", "in": "query", "required": false, "description": "Optional topic filter.", "schema": {"type": "string"}}, {"name": "full", "in": "query", "required": false, "description": "1 includes full stats per row.", "schema": {"type": "integer", "enum": [0, 1], "default": 0}}]}}, "/api/v1/runs": {"get": {"operationId": "list_runs_v1", "summary": "Run list (v1)", "description": "Light v1 list of runs (run_id, topic, gl, status, created, node and edge counts, readiness) for agents checking which topics already exist. 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": "gl", "in": "query", "required": false, "description": "Optional market filter: kr, jp or us.", "schema": {"type": "string", "enum": ["kr", "jp", "us"]}}, {"name": "limit", "in": "query", "required": false, "description": "Rows to scan.", "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100}}]}}, "/api/runs/{run_id}": {"get": {"operationId": "get_run", "summary": "Run record", "description": "Returns the full record of one run: metadata, config snapshot, execution log and result. Large; prefer get_result with slim=1 or get_ontology_digest. 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}, "delete": {"operationId": "delete_run", "summary": "Delete run", "description": "Deletes a run from the store. Requires write access. Returns {deleted, by}. 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/runs/{run_id}/robots": {"get": {"operationId": "get_report_robots", "summary": "Report search visibility", "description": "Returns whether search engines may index this run's report pages (robots index or noindex). Read only; no credits. 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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/compare": {"get": {"operationId": "compare_runs", "summary": "Compare two runs", "description": "Compares two runs of the same topic (e.g. 3 months apart): added, removed and changed nodes and relations, with a noise floor from repeated runs. Warns if topics or markets differ. 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": "old", "in": "query", "required": true, "description": "Earlier run id.", "schema": {"type": "string"}}, {"name": "new", "in": "query", "required": true, "description": "Later run id.", "schema": {"type": "string"}}]}}, "/api/v1/compare": {"get": {"operationId": "compare_runs_v1", "summary": "Compare two runs (v1)", "description": "Stable v1 version of compare_runs for agents: matches nodes by key, then by evidence keywords; no noise floor. 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": "old", "in": "query", "required": true, "description": "Earlier run id.", "schema": {"type": "string"}}, {"name": "new", "in": "query", "required": true, "description": "Later run id.", "schema": {"type": "string"}}]}}, "/api/runs/{run_id}/rerun": {"post": {"operationId": "rerun_build", "summary": "Re-run with same conditions", "description": "Builds a new snapshot of a finished run with the same inputs (topic, gl, sense, seeds, scale, parent). Joins a running build of the same topic if any. Returns the plan plus job_id; poll get_job. Ask the person first. 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-37,000 Data API credits for standard, plus LLM calls. Time: 2-6 minutes. Usually followed by: get_job.", "tags": ["run"], "x-lm-kind": "run", "x-lm-cost": "about 35,000-37,000 Data API credits for standard, plus LLM calls", "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 (12 hex chars). The job id returned by start_build is the same id.", "schema": {"type": "string"}}]}}, "/api/reviews/{key}": {"delete": {"operationId": "delete_review", "summary": "Delete a review mark", "description": "Deletes one stored review decision by key. Changes shared data. 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": "key", "in": "path", "required": true, "description": "Review key.", "schema": {"type": "string"}}]}}, "/api/pins": {"delete": {"operationId": "clear_pins", "summary": "Clear pins", "description": "Removes pinned items. Changes shared data. 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)"}}}}, "/api/runs/reindex": {"post": {"operationId": "reindex_runs", "summary": "Reindex runs", "description": "Rebuilds the run index from stored files. Changes shared data; no credits. 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)"}}}}}, "externalDocs": {"url": "https://daas-intent.listeningmind.ai/agents.md", "description": "Agent guide"}}