# Intent KG: agent guide

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.

## Connect
- MCP: `https://daas-intent.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-intent.listeningmind.ai/.well-known/openapi.json`

## Approval
- read and action tools run at once.
- run and delete tools need a person's approval. Over MCP the tool returns `confirm_url`; show it to the person, then call `confirmation_status` with the token until state is done.
- In the browser the page shows the person a confirm box.

## Workflow
1. `lookup_topic` (read): Use an existing graph at 0 credits if one matches.
2. `check_launch` (read): Before building, check existing runs, parent reuse and the credit estimate.
3. `resolve_topic` (run): Resolve the meaning; if ambiguous, let the person pick a candidate.
4. `start_build` (run): Build the graph after the person confirms (spends credits).
5. `get_job` (read): Read progress until status is done.
6. `get_ontology_digest` (read): Read the result digest.
7. `get_decision_pack` (read): See what can be claimed under the evidence rules.
8. `get_question_pack` (read): Split one real customer question into answerable parts and missing evidence.
9. `get_dossier_md` (read): Get a readable dossier.
10. `export_run` (read): Export in the needed format.
11. `compare_runs` (read): Compare with an earlier run of the same topic.
12. `plan_rerun` (read): For a new snapshot, check conditions and cost first.
13. `rerun_build` (run): Re-run with the same conditions after confirmation.

## Inputs
Topic (required), market (kr/jp/us). Optional: chosen meaning (sense_id) and seeds, seed plan id, scale (standard/extended), parent run for a child topic, force a new snapshot.

## Outputs
Graph with nodes, relations, evidence grades, limits and readiness (graph, tree, map and data tabs), search journey analysis, decision and question packs, node dossier (MD/HTML/PDF), 21 exports (JSON, Agent Pack, Claims, JSON-LD, RDF family, GraphML, Neo4j, CSV, XLSX and more), single-file HTML bundle.

## Cost and time
One standard build costs about 35,000-37,000 Data API credits (median of 49 recent standard runs about 37,000) plus LLM calls and takes 2-6 minutes (up to about 9). Extended costs more; a child run reusing parent clusters costs about 14,000 less. A standard run of the same topic and market within about 20 hours is reused at 0 credits. Meaning resolution is one LLM call; a seed plan is up to about 3,000 credits. Reading stored runs, exports, v1 and v2 cost 0 credits.

## Limits
Markets: kr, jp, us only. A build of a topic and market already in progress is joined instead of duplicated, and a standard run within about 20 hours is reused (use force for a new snapshot). Builds are rate-limited per caller (default 10 per hour) and reserve credit budget before starting. Scale deep is not open. Do not use the SSE stream; call get_job repeatedly. The store keeps 200 runs; older runs keep their link but lose their body (v2 then returns 410).

## Method (how the analysis works)
1. Resolve what the topic means first; if it is ambiguous, a person picks a meaning candidate and its seeds.
2. Collect related searches, clusters and search journeys for the topic.
3. Collect SERPs and AI Overviews.
4. Run a readiness gate and collect more widely when the data is thin.
5. Extract typed nodes (entry situations, choice criteria, brands, pitfalls, thresholds and more) and their relations with evidence grades.
6. Store the graph so lookups, decision and question packs and exports reuse it at 0 credits.

## Reading the result
- readiness.status and ontology.limits tell how complete the graph is and what it cannot support.
- The digest from lookup_topic or get_ontology_digest groups CEPs, KBFs, brands, pitfalls, conventions, heuristics, thresholds and alternatives by type; get_schema explains each type.
- Evidence grades on nodes and relations decide what can be claimed; get_decision_pack applies them and returns a gate verdict.
- get_question_pack splits one customer question into answerable conditions, weak ones and missing evidence.
- stats.finder_credits and stats.serp_credits record the build cost; journeys and clusters show how much evidence was collected.

## Requests this app answers well
- Summarize, with evidence, what people check and what they watch out for when choosing an e-bike
- If a customer asks 'recommend a gentle sunscreen for sensitive skin', split what we can answer with evidence from what is missing
- Compare the robot vacuum graph from three months ago with now and tell me which choice criteria changed
- If there is an air fryer topic graph for the US, export it as JSON-LD

## Continue in another app
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt) (MCP `https://daas-wiki.listeningmind.ai/mcp`): When a brand site in the same category needs wiki pages and an action plan tied to demand. Carry: The run (run_id, or topic and gl); Brand Wiki imports its decision layer as demand data and its knowledge layer as category context at 0 credits.
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt) (MCP `https://daas-icss.listeningmind.ai/mcp`): When you want to run a survey or FGD with a synthetic panel grounded on this topic. Carry: The topic and market; ICSS get_evidence and its grounding pack read stored Intent KG runs without new builds.

## Using the screens (browser agents)
- `describe_screen`: menus, tabs, fields and buttons of the current screen, and what the page is for
- `go_to`: open a menu or page of this app by its label or path
- `fill_field`: type a value into a field by its label (never presses run; runs go through the run tools, which ask the person)
- `read_this_page`: the text and ids of what the person is looking at

## The ListeningMind apps (same account, same tools, call any of them)
Each app has `/mcp`, `/llms.txt`, `/agents.md` and WebMCP on its pages. `family_apps` and `recommend_app` return this list with addresses.
- [ACO](https://daas-aco.listeningmind.ai/llms.txt): Diagnoses whether a product detail page can be cited by AI answers and used by shopping agents (MCP `https://daas-aco.listeningmind.ai/mcp`)
- [AOO](https://daas-aoo.listeningmind.ai/llms.txt): Measures whether AI agents can get real tasks done on a website (MCP `https://daas-aoo.listeningmind.ai/mcp`)
- [Brand Finder](https://daas-brand.listeningmind.ai/llms.txt): Which brands lead search by generation or field, and what their brand assets are (MCP `https://daas-brand.listeningmind.ai/mcp`)
- [Brand Naming Agent](https://daas-naming.listeningmind.ai/llms.txt): Creates and checks brand name candidates grounded in search data (MCP `https://daas-naming.listeningmind.ai/mcp`)
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt): Turns a brand website into the entities, wiki pages and evidence AI assistants read (MCP `https://daas-wiki.listeningmind.ai/mcp`)
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt): In which situations do people start looking for this category (category entry point map) (MCP `https://daas-cep.listeningmind.ai/mcp`)
- [Creative Finder](https://daas-creative.listeningmind.ai/llms.txt): Finds purchase situations (CEP) in search data and drafts a creative, an image and a video for each (MCP `https://daas-creative.listeningmind.ai/mcp`)
- [Demand Forecast](https://daas-forecast.listeningmind.ai/llms.txt): What category demand looks like in the next 3-6 months and when to launch or campaign (MCP `https://daas-forecast.listeningmind.ai/mcp`)
- [Funnel Leak Finder](https://daas-funnel.listeningmind.ai/llms.txt): Where category search journeys leak to competitors (MCP `https://daas-funnel.listeningmind.ai/mcp`)
- [GEO Audit](https://daas-geo.listeningmind.ai/llms.txt): Checks whether a web page is ready to be read and cited by search engines and AI answer engines (MCP `https://daas-geo.listeningmind.ai/mcp`)
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt): Synthetic consumer panel conditioned on search intent, for surveys and FGDs (MCP `https://daas-icss.listeningmind.ai/mcp`)
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt): Finds what consumers ask AI and builds managed brand prompts with AI visibility (MCP `https://daas-prompt.listeningmind.ai/mcp`)
- [Pulse Finder](https://daas-pulse.listeningmind.ai/llms.txt): What is rising in search for a gender and age segment right now (MCP `https://daas-pulse.listeningmind.ai/mcp`)
- [Smart Store Suite](https://daas-store.listeningmind.ai/llms.txt): Which Smart Store products to grow, and how to rewrite their titles and detail pages in searchers' words (MCP `https://daas-store.listeningmind.ai/mcp`)
- [Taste Finder](https://daas-taste.listeningmind.ai/llms.txt): In what sensory and emotional words do people choose this (consumer taste report from search data) (MCP `https://daas-taste.listeningmind.ai/mcp`)
- [ListeningMind Data API](https://daas.listeningmind.ai/llms.txt): the search data behind every app (MCP `https://daas.listeningmind.ai/mcp`) · [glossary](https://daas.listeningmind.ai/en/glossary) · [all apps](https://daas.listeningmind.ai/en/apps)

## Run stages
- `resolve`: Resolve meaning
- `discover`: Collect keywords, clusters, journeys
- `serp`: Collect SERPs and AI Overviews
- `gate`: Readiness gate (expand if thin)
- `ontology`: Extract graph
- `done`: Done
- `error`: Error

## All tools
### lookup_topic
Main agent entry point: matches a topic to the best stored finished run and returns its digest (sense, readiness, CEPs, KBFs, brands, pitfalls, conventions, heuristics, thresholds, alternatives, journey summary, limits, link to the page). Never builds. If nothing matches it returns match=false with reason no_matching_run; then use check_launch and start_build. Read only, free. Cost: free (reads stored runs, 0 credits). Usually followed by: get_ontology_digest, get_decision_pack, get_question_pack.
`GET /api/v1/lookup`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `types`: 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.

### lookup_or_build_topic
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.
`GET /api/v1/lookup`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `types`: 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.
- `build` (required): Must be 1: build when no stored run matches.
- `wait`: Seconds to wait for the build. 0 returns job_id immediately; poll get_job.

### check_launch
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.
`GET /api/launch_check`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `parent_run`: Optional finished run whose clusters a child run would reuse (must be same gl).
- `scale`: Optional scale preset for the estimate. Default standard.

### resolve_topic
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.
`POST /api/resolve`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).

### create_seed_plan
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.
`POST /api/seed_plan`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `seeds`: Optional seeds the person wants included.

### get_seed_plan
Returns a saved seed plan by id (topic, gl, seeds, allocation, credit estimate). Read only, free.
`GET /api/seed_plan/{plan_id}`
- `plan_id` (required): Seed plan id (12 hex chars) from create_seed_plan.

### start_build
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.
`POST /api/build`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `sense_id`: 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`: 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`: Optional full resolve_topic result, passed back as the UI does.
- `force`: true skips joining a running build and same-day reuse and always builds a new snapshot (the UI 'make a new snapshot' button).
- `scale`: 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`: 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.
- `parent_run`: Optional finished run (same gl) whose clusters are reused for a child topic; saves about 13,850 credits.
- `parent_node`: Optional node id in the parent run that this child topic expands.
- `parent_node_label`: Optional label of that parent node.
- `seed_plan_id`: Optional seed plan id from create_seed_plan; topic and gl must match the plan.

### get_job
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.
`GET /api/jobs/{run_id}`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### get_result
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).
`GET /api/jobs/{run_id}/result`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `slim`: 1 returns a slim result without SERP bodies, clusters and journeys.

### get_ontology_digest
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).
`GET /api/v1/ontology/{run_id}`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `view`: digest or full graph.
- `types`: 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.

### get_tree
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).
`GET /api/jobs/{run_id}/tree`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### get_journeys
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).
`GET /api/jobs/{run_id}/journeys`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### get_decision_pack
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).
`GET /api/v2/decision-packs/{run_id}`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `purpose`: exploration, content_brief, or product_claim (strictest evidence rules).

### get_question_pack
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).
`GET /api/v2/question-packs/{run_id}`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `q` (required): The customer question, 2-300 characters.
- `conditions`: Optional conditions, comma-separated; aliases joined with '|', e.g. '세척 용이|세척,밀폐|누수'.

### get_dossier_md
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).
`GET /api/jobs/{run_id}/dossier.md`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `scope`: 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).

### get_dossier_html
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).
`GET /api/jobs/{run_id}/dossier.html`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `scope`: 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).
- `print`: 0 print layout (default), 1 screen layout.

### download_dossier_pdf
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).
`GET /api/jobs/{run_id}/dossier.pdf`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `scope`: 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).

### export_run
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).
`GET /api/jobs/{run_id}/export.{fmt}`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `fmt` (required): Export format.

### get_export_audit
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).
`GET /api/jobs/{run_id}/export_audit`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### download_bundle
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).
`GET /api/jobs/{run_id}/bundle.html`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### get_run_health
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).
`GET /api/jobs/{run_id}/health`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### get_shacl_report
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).
`GET /api/jobs/{run_id}/shacl`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `limit`: Maximum violations to list.

### get_shacl_spec
Returns the SHACL shapes (Turtle) that define valid relations, evidence and entailment rules for all runs. Read only, free.
`GET /api/schema/spec.shacl.ttl`

### get_schema
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.
`GET /api/v1/schema`

### preview_conform
Dry run: shows which relations in a stored run would be rewritten by the current conformance rules (off-spec count before and after, list of changes). Saves nothing. Read only, free. Cost: free (reads stored runs, 0 credits). Usually followed by: apply_conform.
`POST /api/jobs/{run_id}/conform`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### apply_conform
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.
`POST /api/jobs/{run_id}/conform`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `apply` (required): Must be true to save the changes.

### explain_highlight
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.
`POST /api/explain`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `title` (required): Title of the highlight.
- `rule`: Rule that selected this highlight.
- `facts`: Fact lines with numbers (volume, journey counts, quote checks). At most 80 are used, 400 characters each.
- `topic`: Topic of the run.

### list_reviews
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.
`GET /api/reviews`
- `run_id`: Optional run id.

### ai_suggest_reviews
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.
`POST /api/reviews/ai_suggest`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### set_review
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.
`POST /api/reviews`
- `key` (required): Review item key from list_reviews.
- `status` (required): Decision.
- `reviewer`: Optional reviewer name.
- `note`: Optional note.
- `label`: Node label.
- `type`: Node type.
- `topic`: Run topic.
- `run_id`: Run id the item came from.

### list_concepts
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.
`GET /api/concepts`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `limit`: How many recent runs to overlay.

### set_concept
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.
`POST /api/concepts`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `key` (required): Candidate key from list_concepts.
- `action` (required): verify or retire.
- `reviewer`: Optional reviewer name.
- `label`: Optional concept label.
- `aliases`: Optional aliases.
- `definition`: Optional definition.
- `note`: Optional note, e.g. retire reason.

### get_run_concepts
Returns which nodes of this run map to approved concepts ({node_id: concept_id, label, version, due}). Read only, free.
`GET /api/jobs/{run_id}/concepts`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### get_consensus
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.
`GET /api/consensus`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `limit`: How many recent runs to overlay.
- `k`: Optional minimum repeats for entailed.
- `family`: Also include child-topic runs whose parent is this topic.
- `topics`: Optional extra topics, comma-separated, of the same category to overlay.

### list_topics
Lists topics that have finished runs, to choose topics for a combined graph. Read only, free.
`GET /api/topics`
- `gl`: Optional market filter: kr, jp or us.

### get_related_topics
Returns other topics that share identity keys with this topic, with the shared concepts as evidence. Read only, free.
`GET /api/topics/related`
- `topic` (required): Topic word as people search it, e.g. '호텔', 'electric toothbrush'.
- `gl`: Market: kr (Korea), jp (Japan), us (United States).
- `limit`: Maximum topics.

### search_nodes
Searches nodes across all runs by text (cross-run index), optionally filtered by node type. Read only, free.
`GET /api/xindex`
- `q` (required): Search text.
- `types`: 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.
- `limit`: Maximum results.

### list_contradictions
Lists pairs of claims from different runs with similar content but different numbers. Read only, free.
`GET /api/xindex/contradictions`
- `limit`: Maximum pairs.

### list_runs
Lists saved runs newest first (id, topic, gl, status, created, finished, duration, counts, config) plus store stats. Use topic to filter. Read only, free.
`GET /api/runs`
- `limit`: Rows to return.
- `offset`: Rows to skip.
- `topic`: Optional topic filter.
- `full`: 1 includes full stats per row.

### list_runs_v1
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.
`GET /api/v1/runs`
- `gl`: Optional market filter: kr, jp or us.
- `limit`: Rows to scan.

### get_run
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.
`GET /api/runs/{run_id}`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### get_report_robots
Returns whether search engines may index this run's report pages (robots index or noindex). Read only; no credits. Read only, free.
`GET /api/runs/{run_id}/robots`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### compare_runs
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.
`GET /api/compare`
- `old` (required): Earlier run id.
- `new` (required): Later run id.

### compare_runs_v1
Stable v1 version of compare_runs for agents: matches nodes by key, then by evidence keywords; no noise floor. Read only, free.
`GET /api/v1/compare`
- `old` (required): Earlier run id.
- `new` (required): Later run id.

### plan_rerun
Dry run of rerun_build: returns the inherited conditions (topic, gl, sense, seeds, scale, overrides, parent run), the config items that changed since then, the credit estimate and budget. Starts nothing. Read only, free. Usually followed by: rerun_build.
`POST /api/runs/{run_id}/rerun`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.
- `dry_run` (required): Must be true.

### rerun_build
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.
`POST /api/runs/{run_id}/rerun`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### delete_run
Deletes a run from the store. Requires write access. Returns {deleted, by}. Deletes data. A person approves it first.
`DELETE /api/runs/{run_id}`
- `run_id` (required): Run id (12 hex chars). The job id returned by start_build is the same id.

### delete_review
Deletes one stored review decision by key. Changes shared data. Deletes data. A person approves it first.
`DELETE /api/reviews/{key}`
- `key` (required): Review key.

### clear_pins
Removes pinned items. Changes shared data. Deletes data. A person approves it first.
`DELETE /api/pins`

### reindex_runs
Rebuilds the run index from stored files. Changes shared data; no credits. Changes saved data in the app; no credits.
`POST /api/runs/reindex`