MCP reference
Everything a developer or a careful user needs to know about IPGuru's MCP server: where it is, how sign-in works, what each tool does and what it costs. For step-by-step setup, see the guide for your assistant.
Addresses
All addresses use Streamable HTTP. The server is stateless, so any request can reach any instance.
| Address | Tools |
|---|---|
https://mcp.ipguru.ai/mcp | Every tool: brainstorm, structure, deliverables, studio, director and publication. Use this unless your client limits the number of tools. |
https://mcp.ipguru.ai/mcp/brainstorm | Brainstorm tools only. |
https://mcp.ipguru.ai/mcp/structure | Structure tools, plus open_session. |
https://mcp.ipguru.ai/mcp/deliverables | Deliverables tools, plus open_session. |
https://mcp.ipguru.ai/mcp/studio | Studio tools, plus open_session. |
Sign-in
S256). Clients register themselves with dynamic client registration and authenticate at the token endpoint with the client secret they receive. Refresh tokens rotate; reusing an old refresh token revokes the connection.WWW-Authenticate: Bearer resource_metadata="...", pointing to the discovery document below.Authorization: Bearer ...) are for clients that cannot sign in with OAuth. Members make them in the IPGuru app under Account, Connected apps, Make an access key, with the permissions they choose and an expiry of 30, 90 or 365 days or none. The key is shown once. A key stops working when it expires, when the member removes it, or when the member's sign-in ends, for example after a password change.| Endpoint | Address |
|---|---|
| Protected resource metadata | https://mcp.ipguru.ai/.well-known/oauth-protected-resource/mcp (append the family, for example /mcp/brainstorm) |
| Authorization server metadata | https://mcp.ipguru.ai/.well-known/oauth-authorization-server |
| Issuer | https://mcp.ipguru.ai/ |
| Authorize | https://mcp.ipguru.ai/authorize |
| Token | https://mcp.ipguru.ai/token |
| Register | https://mcp.ipguru.ai/register |
| Revoke | https://mcp.ipguru.ai/revoke |
Permissions and cost
Every tool carries one scope tag. A tool that can do several things carries the highest scope any of them needs. Reads, writes and removals sit in separate tools. Every tool also carries MCP annotations: a title, readOnlyHint, destructiveHint, idempotentHint and openWorldHint. Only tools that remove something, or publish or withdraw a public page, are marked destructive.
| Scope | Consent page wording | What it covers |
|---|---|---|
| read | Read your scenarios and records | Reads, catalogues, polling jobs and runs. Free. |
| write | Change scenarios and records | Saving settings, records, cards, descriptions and selections. Free. |
| spend | Put the crew to work and spend your allowance | Crew turns, model and provider work, documents, searches, images and Director runs. Uses the member's allowance, the same as the same action in the app. Some spend tools also have free actions; each tool's description says which. |
A call without the scope it needs is refused with scope_required: <scope>; reconnect with the <scope> scope. The member's membership and allowance still apply to every call.
Limits
| Call duration | Every tool returns within 45 seconds. Longer work is a job, a turn or a run that the client polls. |
| Request rate | 10 requests a second per connection per address, with bursts up to 30. |
| Sign-in routes | 30 requests a minute per IP address. |
| Uploads | 15 MiB per file (Vault objects and references). Public web pages added as sources: up to 15 MB. |
| Pages | Transcript and event reads return at most 200 events per call. Lists return a cursor for the next page. |
| Activity record | Each call is recorded in the member's activity by tool name, connector version and connection. Arguments, results and credentials are not stored in that record. |
How the tools work
Call open_session first. It returns a session handle that every other tool takes, with the account summary, the first scenario cards and server defaults.
Anything that takes more than a few seconds returns an id at once. Poll it with the matching tool: wait_for_turn for a crew turn, document_run for a document, studio_run_status for an image, director_run_status for Director, and the *_job tools for other jobs. Pass wait_s (up to 45) to wait for progress. still_running means call again. A wait ending does not stop the work.
Writes that change shared records take the current revision from the last read. A stale revision is refused with a conflict. Read again and decide; do not retry blindly.
Tools that start paid work accept a caller-chosen client_request_id, idempotency_key or command_id. After a lost reply, repeat the call with the same identity and body, or look it up first with turn_request, read_preparation or the job status. You get the original work back instead of a second charge.
A finished crew turn returns the open cards: options and recommendations waiting for the member. A new message does not answer or close a card. Use card_act. review_open_items lists everything waiting on the member.
Scenario tools return an app_url that opens the same saved work in the IPGuru app.
playbook(mode) returns IPGuru's current guide for a workflow. The same guides are available as MCP prompts.
Prompts
| Prompt | Arguments | What it does |
|---|---|---|
harness | topic (optional) | Guide a brainstorm with the crew, optionally starting from a topic. |
structural | topic (optional) | Use IPGuru's method to structure the client's own thinking. |
audit | scenario_id | Audit a scenario's current signals and pick three actions. |
pack | scenario_id, action_id (optional) | Choose or start a document pack, then return its documents. |
studio | scenario_id | Prepare a scenario's Studio and review its images. |
director | scenario_id | Plan, follow and review a Scenario Director run. |
debate | scenario_id | An expert debate. A last resort, after discussion, questions, research and critique. |
Resources
Read these with the client's resource support, or with the fetch tool.
| Resource | What it holds |
|---|---|
ipguru://scenarios | The member's scenario cards. |
ipguru://scenarios/{scenario_id} | One scenario card. |
ipguru://scenarios/{scenario_id}/transcript | The transcript with speaker names and roles. |
ipguru://scenarios/{scenario_id}/idea | The Idea record. |
ipguru://scenarios/{scenario_id}/signals | The signal matrix. |
ipguru://scenarios/{scenario_id}/record | The scenario record: decisions and suggestions. |
ipguru://scenarios/{scenario_id}/lens | The active frame, theme and coverage. |
ipguru://catalog/{kind} | One catalogue. |
ipguru://scenarios/{scenario_id}/documents/{run_id}/{kind} | A finished document: markdown, docx or pdf. |
ipguru://scenarios/{scenario_id}/references/{reference_id} | One reference. |
ipguru://scenarios/{scenario_id}/vault | The scenario Vault listing. |
ipguru://scenarios/{scenario_id}/vault/files/{file_id}/versions/{version_id} | One Vault file version. Add /thumbnail for its thumbnail. |
ipguru://scenarios/{scenario_id}/studio | The Studio record: description, art direction, shoot list, roles and runs. |
ipguru://scenarios/{scenario_id}/visual/images/{image_id} | One image. Add /thumbnail for its thumbnail. |
Files too large to return open in the app instead: the scenario's Documents, Studio or Vault.
Tools
The descriptions below are the ones the server gives your assistant.
Sessions, scenarios, crew turns, cards, follow-ups, the crew, comparisons and debate.
| Tool | Scope | What it does |
|---|---|---|
open_session | read | Call first. Verifies the signed-in token and returns the session handle every other tool takes, the account summary, the scenario cards and the server defaults. Free. |
search | read | Find scenario, library and reference records by words in their titles, questions, topics, notes or source URLs. This is a projection over the three lists, not a server search index; every query word must match. Needs open_session; references additionally need scenario_id. Free. Results include an exact id for fetch and the app's Brainstorm entry URL; the app does not yet route individual result IDs. |
fetch | read | Read a resource by its ipguru URI, or the full record for an id from search: scenario:<id>, library:<id> or reference:<scenario_id>/<id>. Needs open_session. Free; a scenario includes its transcript page and next_after cursor, and a reference includes its content. |
focus | read | List focused references after open_session and selecting a scenario. Free. |
add_focus | write | Add a focused reference with scope keep or once. Needs open_session, a scenario and reference_id from list_references. Free. |
clear_focus | write | Clear focused references after open_session and selecting a scenario. Pass reference_id to clear one reference; omit it to clear all focus. Free. |
participant_act | spend | Mute or unmute an agent, set in_character or out_of_character, or run_action using an action_id from the participant's available actions. Needs open_session, a scenario and the card's revision for mode changes. Mode changes are free; run_action runs a model. |
extract_roles | spend | Extract useful roles from the scenario after a conversation establishes the idea. Needs open_session and a scenario. Runs a model and is metered. |
set_response_profile | write | Set the scenario's response format, length, tone, preset or custom instructions. Needs open_session and the card's revision; omitted options remain unchanged. Free. |
set_crew_participation | write | Enable or disable a seated crew participant after read_consultation identifies them. Needs open_session, the scenario, participant_id and the card's revision. Free. |
read_roster | read | Read available participants and their roles after selecting a scenario. Needs open_session. Free; use returned identities for participant actions. |
read_crew_expert | read | Read the generated overview of an expert currently seated in the scenario. Needs open_session and profile_id from read_consultation. Free; an unseated profile is refused. |
feature_guide | read | Read the feature guide after open_session and selecting a scenario. Free. |
feature_guide_act | write | Record a feature-guide episode with claim, shown, visited or dismissed. Needs open_session and a scenario; claim needs episode_id, other actions need feature or episode_id from feature_guide. Free. |
list_scenarios | read | Read saved scenario cards, Idea-completeness scores with freshness, publication status and app links. Free; never runs a model. Needs open_session. Follow next_cursor for more; limit is 1 to 100. A score is not patentability or Director completion. |
start_scenario | spend | Create a scenario from a centre topic after open_session. mode brainstorm opens a conversation; mode expand also queues and returns its initial expansion job. Creation queues background model-backed Topic Map work even with generate_title false; optional title generation and expansion may add metered work. preparation=wizard commissions the UI's durable Idea/roles/crew/greeting/source setup for brainstorm mode; use read_preparation. Default none retains raw creation. Retain client_request_id BEFORE sending, then reuse it after a lost response to avoid duplicate scenarios/spend. chat_mode is nova, synthesised or roundtable; send_message then wait_for_turn runs a conversation turn. |
read_preparation | read | Read durable wizard preparation progress after start_scenario. Free; a queued job is not completion. Work continues after disconnect. |
prepare_scenario | spend | Commission shared wizard conversation preparation for an existing scenario, or return its existing job. May spend on Idea/crew/sources; needs current scenario revision. Inspect with read_preparation. |
retry_preparation | spend | Resume unfinished conversation preparation using its current scenario revision. Keeps completed stages. An uncertain interrupted stage requires explicit retry_uncertain after review and may spend again. |
contrib_summary | spend | Summarise selected crew contributions after read_events or read_scenario gives their event indexes. Pass event_indexes and the optional synthesis_index exactly, including zero. Needs open_session and the owned scenario. Uses the API's lazy contributor analysis; analysing nonempty contributions calls a metered model. Returns its actual summary. |
turn_request | read | Look up the turn for client_request_id retained from send_message or queue_followup after an ambiguous disconnect. Needs open_session and the same scenario. Free; returns acceptance, saved/completed flags and the turn when it exists. A queued input has no turn until run-next starts it, so accepted false does not prove the input was lost. Check list_followups before resending and reuse the same key. |
validate_scenario | read | Read the existing scenario's project, knowledge, memory and storage readiness after open_session, before investigating an unavailable feature. Free diagnostics, with no repair or infrastructure change. The existing read_validation tool remains available. |
debate_motions | read | Advanced, last-resort expert debate: use only after crew discussion, questions, research and critique have failed to resolve the issue. Read suggested motions. Call open_session first, then read_roster to choose the debaters. Free. |
compare_scenarios | spend | Compare two to four owned scenarios after open_session and list_scenarios. persist false returns only their transient scope bundle, without a model analysis or merge. persist true creates a deterministic, tier-metered comparison with frozen inputs and a proposal. Keep its comparison_id and idempotency_key, then read and review it with comparison before any apply. Sources are not changed. |
comparison | read | Read a persisted comparison after open_session and compare_scenarios(persist true). Free; reading does not run a model. |
apply_comparison | write | Apply only a persisted comparison's reviewed accepted_proposal to a separate owned target_scenario_id after open_session and comparison. The target must not be one of the sources. Stores the accepted proposal in the target's compare-merge history and advances its revision; it does not rewrite the consolidated Idea fields. Omitted accepted_proposal uses the saved proposal. Deterministic and free, with no model call. Keep the returned idempotency_key for the same apply retry. |
debate | read | List or read saved expert debates after open_session and selecting a scenario. Read needs debate_id from the list or debate_act(create). Free; use debate_status to wait for a revision or status change. |
debate_act | spend | Advanced, last-resort expert debate. Commission only after ordinary crew discussion, questions, research and critique have failed; never for routine coverage. Create after open_session, debate_motions and read_roster, passing the scenario_revision and chosen profiles. Create records the motion and cast; it does not generate a turn. Advance queues metered model work; autoplay commissions a bounded sequence. Keep its job_id for generation_job and use debate_status to read the debate itself. Control, cast, interject, next_motion and dispose only edit the record. Every edit after create needs the debate's current revision. Interject records your point for a later advance; dispose sends a reviewed disposition to the scenario as send_suggestion or leaves it open. Control accepts pause, resume, pace, steer, end or next_motion. Keep the returned idempotency_key for create and advance retries. Paused or active describes the debate, not its job. |
debate_status | read | Read a debate after create or advance. With wait_s, poll for at most 45 seconds and report its actual status, phase and turn count. Pass after_revision from the preceding read to return as soon as a newer step is saved. Otherwise wait for a revision change or a status outside active/queued/running. active can mean waiting for your next advance, so it does not prove a worker is running; use generation_job with advance's job_id for worker failure or completion. wait_exhausted preserves the actual debate status. Free after open_session. |
read_scenario | read | The scenario card, its participants, chat mode and the transcript projected to speaker names and roles, from transcript_after onwards (at most 200 events; loop on next_after; the default -1 includes the first event at index zero), with each message's cards and open_card_count; review_open_items lists the open ones. Free. |
update_scenario | write | Rename or re-centre a scenario, or change its question presets. Needs the card's current revision; a stale revision answers a conflict. Free. |
send_message | spend | Send the user's message to the crew. Queues it as a follow-up and hands the turn to the worker; returns the queue state and the active turn. When a turn is already running the item stays queued and the worker runs it after that turn; the response names the active turn. Then call wait_for_turn with the turn_id. Costs a model turn. Returns client_request_id for turn_request lookup; supply and retain your own key before sending if a lost reply must be recoverable. Reuse that key for the same input: replay returns its recorded state without running another queued turn. If it never started, inspect list_followups before explicitly choosing followup_act(run_next). |
wait_for_turn | read | Wait for a turn to finish, at most timeout_s seconds (capped at 45), then return the new transcript events since after_event (default -1 includes index zero) with speaker names and roles. status still_running means call again with the returned next_after; it is not an error. Reports the crew's activity and new contributors while waiting. Once the turn has finished it also returns open_cards and open_card_count: a card stays open until card_act answers or closes it. Free; loop until status is completed, failed, stopped or cancelled. |
read_events | read | The raw event page after the requested index, at most 200 per call. The default -1 includes index zero. Free; prefer read_scenario for a transcript with speaker names. |
review_open_items | read | Everything waiting on the member: the open cards (options and recommendations the crew raised that read Needs review in the app), the pending suggestions in the scenario record and the latest Director run's open questions. Each row names what closes it: card_act, suggestion_act (dismiss, park or adopt) or director_control(answer). Call it before handing back to the member. Free. |
card_act | spend | Answer or close one card by proposal_id, with the actions the app offers. accept (a recommendation), choose (option_id or option_text) and choose_many (selections of {option_id, priority primary or secondary}) record the answer and queue Nova's reaction, a metered model turn. record (destination ruled_out, parking, actions, suggestions or decisions), ignore, undo and reopen are free and run no model; close a pile of cards with those. To ask about a card, use send_message; that neither answers nor closes it. Returns the API result and the card as it now reads. |
stop_turn | write | Stop a running turn. Returns the queue state. Free. |
list_followups | read | The follow-up queue: queued items, the active turn and capacity. Free. |
queue_followup | write | Queue a follow-up without starting it (behavior queue), or steer the running turn (behavior steer). Free to queue; the later turn is metered. send_message is queue plus run-next. Returns client_request_id; retain or supply it for the same input's retry. Before resending after a lost reply, inspect list_followups and turn_request. |
followup_act | spend | Act on the follow-up queue: edit (item_id, text), reorder (item_id, position), promote an item to a steer (item_id), run_next, or resume after a stop. run_next and resume can start a model turn and are metered. |
remove_followup | write | Remove a follow-up from the queue after open_session and selecting a scenario. Needs item_id from list_followups. Free. |
set_chat_mode | write | Set how the crew answers: nova (one voice), synthesised (experts, Nova sums up) or roundtable (every voice). Needs the card's revision. Free. |
apply_theme | write | Apply a theme pack by key (see the structure server's catalog theme_packs), or clear it with no key. Needs the card's revision. Free. |
apply_frame | write | Apply a thinking frame by key (catalog frames), or clear it with no key. Needs the card's revision. Free. |
recommend_experts | spend | Ask for a recommended roster of experts for the scenario; alternate asks for a different set, force re-runs it. Runs a model: costs a model call. Seat them with set_experts. |
set_experts | write | Seat the experts by profile id (from recommend_experts). Needs the card's revision. Omit profile_ids to choose from the saved recommendation. This asks before acting where the client can ask. Clients without choices need explicit profile_ids. Free. |
greet | spend | Ask Nova to open the conversation. The greeting is an appended event, not a turn: this call returns it as events with speaker names. If the card's recommendation_state is pending the crew is still being seated and the greeting names no experts; call read_scenario until it is ready first. Calling greet again returns the existing greeting (already true). Costs a model call the first time. |
duplicate_scenario | write | Copy a scenario's settings into a new one (never its transcript). Free. |
delete_scenario | write | Delete a scenario. Pass the card's revision while it is live; deleting again is idempotent. The scenario leaves every list at once and is erased in the background: read_scenario reports status deleting until then, 404 once it is gone, or delete_failed if the erasure could not finish. This asks before acting where the client can ask. Free. |
The Idea record, signals, the expander, the pivot, questions, verification and the catalogues.
| Tool | Scope | What it does |
|---|---|---|
apply_expansion | write | Apply the kept expansion items after read_expansion and mark_expansion. Needs open_session, a scenario and the returned expansion_revision. Free. |
recollect_expansion | write | Recollect the expansion against the current scenario after read_expansion. Needs open_session, a scenario and expansion_revision. Free; read the returned revision before editing. |
register_act | write | Act on the Idea's assumptions, tests or open_gaps after read_idea. Actions are add, correct, settle, withdraw, record_result, not_running and resolve; the API checks which actions fit each lane. Needs open_session and the card's revision. Pass item_id for an existing entry. Free. |
delete_register_entry | write | Delete an entry from the Idea's assumptions, tests or open_gaps after open_session and read_idea. Needs lane, item_id and the card's revision. The API checks which lanes permit deletion. Free. |
restore_idea | write | Restore a saved Idea revision after checking the current Idea and scenario card. Needs open_session, target_revision, expected_idea_revision and the card's revision. Free. |
question | write | Create or edit a custom question after open_session and catalog(questions). Create needs question_text; edit needs question_id and the question's revision. Free. |
delete_question | write | Delete a custom question after open_session and catalog(questions). Needs question_id; optional question_text names the confirmation. Removes the question and asks before acting where the client can ask. Free. |
read_validation | read | Check the selected scenario's project, knowledge, memory and storage readiness before investigating an unavailable feature. Needs open_session and a scenario. Free; returns the API's diagnostic results without changing infrastructure. |
start_verification | spend | Start a verification method after catalog(verification_methods), read_signals or read_idea. Needs open_session, a scenario, method_key and idea_revision; optionally bind a risk_signal_key, assumption_id or consultation_id. Runs a model and is metered; poll the returned run_id with verification_run. |
verification_run | read | Poll the run_id returned by start_verification. Needs open_session and the same scenario. Free; the returned result records its evidence and outcome. |
question_scan | read | Read the structural question scan after open_session and selecting a scenario. Free. Use question_scan_act to start a scan or dismiss a question. |
question_scan_act | spend | Start a structural question scan or dismiss a question by question_id from question_scan. Needs open_session and a scenario. Dismissing is free; start runs a model and returns a generation_job handle. Read question_scan again when done. |
generation_job | read | Poll a job from question_scan_act or list generation jobs when job_id is omitted. Needs open_session and the same scenario. after continues job events; action and target_id filter the list. wait_s waits up to 45 seconds with progress for one job. Free; read the generated surface after completion. |
playbook | read | The structured-brainstorm walk as text: mode harness (Claude drives the crew for a person), structural (the caller thinks and IPGuru scaffolds), pack, audit, studio, director or debate. Free; read it before starting that workflow. The same guidance is available as prompts. |
catalog | read | One of IPGuru's catalogues, unchanged from the route: starters, questions, intents (with the intent JSON schema), signals, dimensions (the eight axes A to H, from the signal catalogue), frames, methods, verification_methods, theme_packs, design_criteria, quick_actions, source_kinds (reference classifications) and invention_profiles (the subjects, claim forms and special handling an invention profile is made of). Needs open_session. Free. |
set_intent | write | Set the strategic intent stack (entries from catalog intents) and re-weight the dimensions. Needs the card's revision. Free. |
set_invention_profile | write | Confirm or change what the invention is: one subject and one or more claim_forms, keys from catalog(invention_profiles). Studio makes nothing for a scenario until this is confirmed. It is the person's decision: ask them, and never confirm a guess. Changing a confirmed profile keeps earlier Studio work, labels it as made for the old profile and returns how many outputs that was. Needs the card's revision. Free. |
read_idea | read | The Idea record: overview, fields, decisions, will-nots, assumptions, next tests, actions, remaining gaps and the parking lot. Free. |
refresh_idea | spend | Ask Nova to re-consolidate the Idea from the transcript (focus all or summary). Runs a model: metered. Returns the Idea view. |
score_idea | write | Persist the current deterministic Idea-completeness rubric and dimensions. No model call; free. Does not assess patentability or prove Director completion. |
read_signals | read | Read the signal audit after audit_signals, or check whether an audit is available. Optionally select one dimension by its A to H letter or catalogue key; all other audit metadata is retained. Needs open_session and a scenario. Free. |
frame_coverage | read | List frames and coverage states or read a frame's slots after open_session and selecting a scenario. Read needs frame_id from the list. Free; evaluate_frame_coverage runs a new evaluation. |
evaluate_frame_coverage | spend | Evaluate coverage for a frame_id from frame_coverage after open_session and selecting a scenario. Runs a metered model; read frame_coverage afterwards for the result. Accepts an optional manifest_version. |
read_connections | read | Read the connections of a knowledge-map record after selecting its record_type and record_id. Needs open_session and a scenario. Pass the returned cursor for the next page; limit is optional. Free. |
read_lens | read | Read the active frame, theme and frame coverage together after selecting a scenario. Needs open_session. Free; coverage_available is false when the knowledge map is disabled. |
audit_signals | spend | Start a signal audit against the Idea at idea_revision (from read_idea or read_signals). A job: returns the job id; poll with signals_job. |
signals_job | read | Poll a signal audit job by id after open_session. wait_s waits up to 45 seconds with progress. Free. |
signal_act | spend | Act on one signal: dismiss or restore it (free), or suggest from it (runs a model; suggest_action names what to suggest). Needs the card's revision. |
read_evaluation | read | The Idea evaluation. Free. |
read_expansion | read | The expansion state and its expansion_revision, which every expander write needs. Free. |
generate_expansion | spend | Ask the expander for items: seed text, depth same, deeper or wider, an optional section_key, focus_item_id, recentre_direction_id or method_key. Runs a model and takes tens of seconds: a job; returns the job id, poll with expansion_job. Needs expansion_revision from read_expansion. |
expansion_job | read | Poll an expansion job by id. The items arrive on the expansion state when it is done. wait_s waits up to 45 seconds with progress. Free. |
cancel_expansion_job | write | Cancel an expansion job by id after open_session and selecting a scenario. Stops work and retains the job record. Free. |
mark_expansion | write | Record the caller's judgements on the expansion: locked, declined and restored item ids, adjacent direction ids, authored items and which sections are open. Free, and it must precede commit_expansion. Needs expansion_revision. |
undo_expansion | write | Undo the last expansion mark. Free. Needs expansion_revision. |
commit_expansion | spend | Commit the marked expansion into a scenario: title, summary, frame_key (catalog frames), optional theme_key; preview true returns the committed shape without committing. Runs a model: metered. Needs expansion_revision. |
pivot | spend | Move the idea: action start (optional seed) opens a pivot and returns its pivot_id; advance (pivot_id, answers, direction forward or back) moves through it; commit (pivot_id, optional title, frame_key, theme_key) commits; cancel (pivot_id) drops it. start, advance and commit run a model: metered. Needs the card's revision. |
read_record | read | The scenario record: decision rows and the Idea's register. Free. |
record_act | write | Act on record rows in bulk: reverse, park, complete, activate, adopt or dismiss the items (each an object naming the row, as read_record returns them). Needs the card's revision. Free. |
suggestion_act | write | Act on one suggestion in the scenario record by id: discuss, adopt, park, debate, dismiss, reopen, accept or edit (with text). Needs the card's revision. Free. |
lens_helpers | spend | Run a lens helper (lens_kind frame or theme, helper name, target_key) against the Idea at idea_revision. Runs a model and is metered. A job: returns the job id; poll with lens_helpers_job. |
lens_helpers_job | read | Poll a lens helper job by id after open_session. wait_s waits up to 45 seconds with progress. Free. |
Documents, references, web sources, consultations, the knowledge map, the Vault, the library and project drafts.
| Tool | Scope | What it does |
|---|---|---|
vault | read | List the scenario Vault after open_session and selecting a scenario. Free. The listing supplies vault_object_id for linking and file/version IDs for the Vault resources. |
link_vault_object | write | Link an existing Vault object after open_session and selecting a scenario. Find vault_object_id in vault; scope is scenario, shared or thumbnail. Free. |
unlink_vault_object | write | Unlink a Vault object after open_session and selecting a scenario. Find vault_object_id in vault. Removes only the association, never the file. Free. |
upload_vault_object | write | Upload and link a file to the scenario Vault after open_session. Pass filename, its bytes as content_base64 and optional content_type. Free; the default local cap and API landing limit are 15 MiB. The API owns storage and validation. Read vault afterwards for file/version IDs and the file resource; do not repeat an upload merely to poll its status. |
knowledge_map | read | Read the canonical knowledge graph after open_session and selecting a scenario. Use action subgraph with a root_id from read; depth, nodes, links and fanout bound the result. Export accepts revision. Reads and exports are free. The API reports disabled features or unavailable revisions. |
refresh_knowledge_map | spend | Refresh the canonical knowledge graph after open_session and selecting a scenario. Can queue metered alignment; read knowledge_map afterwards. The API reports disabled features. |
knowledge_disposition | write | Record a knowledge review after open_session and knowledge_map. record_type is knowledge_item, knowledge_statement, knowledge_work_item or knowledge_relationship; record_id comes from the graph. Set epistemic_state and optional review or lineage fields. Free; the API validates states and retains review history. Reuse an explicit client_request_id to retry the same disposition safely. |
shared_gap_lifecycle | write | Update a shared knowledge gap after open_session and reading the graph or frame coverage. Pass shared_work_item_id and action record_answer, propose_closure, confirm_closure or reopen. Evidence uses existing evidence_anchor_ids; reopen needs a reason. Free; the API decides the resulting gap and linked-slot states. |
document_export | write | Build a docx or pdf export from a completed document run after open_session. The API builds and stores the file during this call; no model call is needed. An existing export is returned as saved. When document_run lists the format in obsolete_exports, pass refresh=true to render the same saved text again with the current layout as a new file; the earlier file is kept and a repeat converges. Returns the existing run_id, pollable with document_run, and the built file's ipguru://scenarios/<scenario_id>/documents/<run_id>/<format> resource. The API controls availability and free-tier PDF watermarking. |
upload_reference | write | Upload a document as a scenario reference after open_session. Pass filename, its bytes as content_base64 and optional note or evidence_for; source_url is for a saved HTML page. The default limit is 15 MiB. The API stores the file and queues extraction. The returned run_id is the reference_id: pass it as reference_id to read_reference, or find it with list_references. Uploading is free; subsequent model-backed reading uses read_references and is metered. |
read_coverage | read | Read what the scenario has covered and what remains after working on the idea. Needs open_session and a scenario; documents true includes document coverage. Free. |
library | read | List or read library entries after open_session. Read needs entry_id from the list. Free. |
library_act | write | Publish a scenario Vault object, replicate a library entry into a scenario, or designate its replica after open_session. Find vault_object_id with vault and entry_id with library. Publish needs scenario_id and vault_object_id; replicate needs scenario_id and entry_id; designate needs entry_id and replica_id. Free. Publishing shares the file through the library. |
unpublish_library_entry | write | Unpublish a library entry after open_session and library. Needs entry_id; optional title names the confirmation. Removes the shared entry and asks before acting where the client can ask. Free. |
read_references | spend | Start reading prepared references after list_references shows they are ready. Needs open_session and a scenario; omit reference_ids to read all ready references. Runs a model and is metered; poll the returned run_id with reference_read_run. |
reference_read_run | read | Poll a run_id from read_references in the same scenario. Needs open_session. wait_s waits up to 45 seconds with progress. Free; read_reference(answers=true) shows the answers when complete. |
canonical_sites | spend | Recommend sources, suggest a URL as an unapproved candidate, or crawl a reviewed selection. Needs open_session and a scenario; suggest needs url and optional note; crawl needs source_ids or sites the member has reviewed. Suggesting is free; recommendation and crawling may run a model and are metered. Poll a returned job_id with knowledge_job; read_knowledge shows the source state. |
list_consultations | read | List a scenario's saved expert consultations, optionally filtered by kind. Needs open_session and a scenario; use read_expert_consultation for a result. Free. |
run_consultation | spend | Commission critique, perspective, sales, stress_test or voc after choosing a scenario and any expert profiles. Needs the card's revision. Runs a model and is metered; returns a job handle to poll with consultation_job, then read_expert_consultation. Omit kind to choose; this asks before acting where the client can ask. Clients without choices need an explicit kind. |
consultation_job | read | Poll the job from run_consultation or consultation_act, or list jobs by kind and subject_key when job_id is omitted. Needs open_session and the same scenario. wait_s waits up to 45 seconds with progress for one job. Free; read_expert_consultation after completion shows the findings. |
read_expert_consultation | read | Read findings and recommendations after consultation_job completes or after list_consultations. Needs open_session, the scenario and consultation_id. Free; read the card's revision before acting on findings. |
consultation_act | spend | Act after read_expert_consultation: act_findings needs finding_ids and finding_action; act_recommendation needs recommendation_id and recommendation_action; append_suggestions needs suggestion_ids. These are free. regenerate and generate_instrument run a model and return a consultation_job handle; the instrument is for voc and needs its consultation_revision. Every action needs the card's revision and open_session. |
list_documents | read | The document actions available to this scenario at the account's tier, with the runs and artefacts so far. Free. |
start_document | spend | Start a document run for an action_id from list_documents, optionally revising an earlier run (revises_run_id). A job: returns the run id; poll with document_run. Metered by tier. Omit action_id to choose an available pack; this asks before acting where the client can ask. Clients without choices need an explicit action_id. |
document_run | read | Poll a document run by id after open_session. wait_s waits up to 45 seconds with progress. Free. |
document_artifact | read | Read a finished run's artefact. kind markdown returns the text; Word and PDF return a resource link to the built file, also available in the app's Documents. Free. |
document_act | spend | Act on a document run: accept it, revise it (with notes; a job, poll document_run), cancel a running one, or dismiss a finished one. Free except revise. |
list_references | read | The scenario's references with relevance. Free. |
search_references | spend | Search for references answering a question (optionally from one source_url). A job: returns the reference id; poll with read_reference. Metered. |
read_reference | read | Read a reference after list_references or search_references. content true includes its source content; answers true includes its extracted answers. Needs open_session and the same scenario. Free. |
add_web_page | spend | Add one public web page (HTML or PDF, up to 15 MB) as a scenario source by its address. The server reads that page only, from a public address: private or internal addresses, sign-ins and the rest of the site are refused. A job: returns the reference id; poll with read_reference. A page filed as a challenge kind is then read for its criteria; see read_challenge_fit. Metered. |
read_challenge_fit | read | Read how the Idea fits the challenge it answers: each challenge document (rules, brief, call or platform guidelines) with its criteria in document order, the document's own quotation and locator, each criterion's fit state and reason, and counts by state. There is no total or percentage, and the fit never changes the Idea score. goal_questions are the criteria that stand in for a goal's standard questions. Needs open_session and a scenario. Free. |
check_challenge_fit | spend | Check the Idea against one challenge document again, by reference_id from read_challenge_fit. Reads its criteria first when they are missing, failed or out of date. A job: returns job_id; poll with read_challenge_fit until that document's fit state is current or failed. Needs open_session. Metered. |
reference_act | spend | Act on a reference: relevance (explain one citation by citation_index; runs a model), retry a failed fetch or search (a job), note (title, note, evidence_for), set source_kind from catalog(source_kinds), or mine its contents. source_kind null clears classification; mine requires a kind first. Needs open_session and a reference from list_references. Free except relevance and mine, which run a model. |
remove_reference | write | Remove a reference after open_session and list_references. Needs scenario_id and reference_id; optional title names the confirmation. Asks before acting where the client can ask. Free. |
read_knowledge | read | The scenario's knowledge map. Free. |
generate_topic_map | spend | Generate the topic map. A job: returns the job id; poll with knowledge_job; read the map with read_knowledge when the job is done. Metered. |
knowledge_job | read | Poll a topic map job by id from generate_topic_map. Read the completed map with read_knowledge. wait_s waits up to 45 seconds with progress. Free. |
read_consultation | read | Read the seated crew and their consultation state after selecting a scenario. For the expert consultations see list_consultations. Needs open_session. Free. |
disclosure | read | Read the member's account-wide disclosure log after open_session. List returns saved entries; bearing and offers need scenario_id and return subject overlap or mined offers, without judging patentability or legal deadlines. Deterministic and free. |
disclosure_act | write | Create or update the member's account-wide disclosure log, or accept_offer or decline_offer after open_session and disclosure. Create records only the facts and dates the member supplies. Update needs disclosure_id; omitted fields stay unchanged and empty strings/lists clear optional fields. accept_offer records the member's confirmed facts for reference_id; decline_offer records their refusal. All actions are deterministic and free; create has no retry key. |
delete_disclosure | write | Permanently remove one entry from the member's account-wide disclosure log after open_session and disclosure. Needs disclosure_id. Removes only that log entry. Deterministic and free. |
project_draft | spend | Prepare the current scenario's editable Project Wizard source after open_session and read_scenario. Reuses a revision-pinned import when enabled; otherwise returns the API's legacy draft. Deterministic, with no model generation. Read the returned import_id before refresh_project_import; this does not submit a project. |
refresh_project_import | spend | After project_draft, refresh its import_id against the latest scenario. Returns the API's bounded diff without overwriting Wizard edits. Deterministic, no model call. Needs open_session; preserve disabled-snapshot or ownership refusals. |
publication_import_draft | read | Read your private import draft for a published template slug after open_session. Free. Review the draft before save_publication_import_draft or publication_import_act(create). All state lives in the API. |
save_publication_import_draft | write | Save your private import draft after open_session and publication_import_draft. Pass expected_revision and the reviewed edition, seed/full mode, name, seed fields and open_in_expand choice. Replaces these choices; it does not import or generate anything. Free. Use publication_import_act(create) only after reviewing the draft. All state lives in the API. |
publication_import | read | Read an existing private publication import after open_session. Pass import_id from publication_import_act(create). A completed copy is not an assessed idea or a model-generated expansion. Free; preserves lifecycle and ownership refusals. |
publication_import_act | spend | Create a private copy from the published slug and reviewed edition/seed/full choices after open_session and publication_import_draft. Create queues provisioning and import work, returning import_id; publication_import follows that existing import. A completed copy is not an assessed idea or a model-generated expansion. Retry resumes only an API-permitted failed import after you inspect its reason; a terminal import is returned unchanged. Cancel stops the import and archives its retained private copy. Keep the returned create idempotency_key and preserve quota, lifecycle and ownership refusals. No direct model call; downstream work stays under the API's limits. |
Studio descriptions, art direction, shoot lists and image runs.
| Tool | Scope | What it does |
|---|---|---|
studio_run | spend | Commission turnaround, detail_sheet, take, model3d or video after open_session and read_studio. Save a current description first and pass its revision; take also needs a shot key, with phase/component/direction where required; turnaround takes a sheet from read_studio's catalogue sheets (default product_sheet). Media uses prompt. Metered by tier; reuse idempotency_key to retry the same request. Poll the returned run_id with studio_run_status; never start a replacement to poll. |
studio_run_status | read | Read Studio and media runs after open_session, or poll the run_id from studio_run or shoot_list(run). Free. wait_s waits at most 45 seconds with progress, then returns still_running with the last state. Ready image runs include resource URIs. needs_input or needs_review requires attention; unavailable is terminal and preserves the API's provider refusal. Do not start a replacement generation automatically. |
studio_run_act | spend | Dismiss a failed Studio run, cancel an unfinished image run, or retry a failed media run after open_session and studio_run_status. Dismiss and cancel are free; work already sent to the image provider may still be charged, and a settled run is returned unchanged. Retry is media-only and can incur provider costs. The API decides whether its persisted state permits the action. |
studio_candidate | write | Approve a turnaround or accept a candidate after open_session and read_studio. Inspect the image resource and quality result first. Free. Approval and selection remain subject to the API's currentness, scope and quality checks. |
dismiss_studio_candidate | write | Dismiss a Studio candidate after open_session and read_studio. Needs candidate_id. Removes the image from its gallery and roles, with no restore route. Free. |
read_visual | read | Read the scenario's compatibility visual description after open_session. Free; read_studio has the full Studio record. |
set_visual | write | Save the compatibility visual fields after open_session and read_visual. Pass the current scenario revision and all five fields; omitted fields become empty. Free. |
generate_image | spend | Request an image through the compatibility visual action after open_session and read_visual, passing the current scenario revision. Metered; the API's queued result and any missing-description or tier refusal are returned unchanged. |
read_studio | read | Read Studio's description, art direction, shoot list, roles and image runs after open_session and selecting a scenario. Free. Use its revision for edits; description and art_direction contain the shapes their save tools accept. |
studio_description | read | Read the history of a Studio description after open_session and read_studio. Free. |
studio_description_act | spend | Set or generate a Studio description after open_session and read_studio. Set commits a new description version at once; it needs document in the record's description shape, pending questions and its revision. Generate writes its result into the description draft (read_studio draft), which the next product sheet locks as a version; it needs parts and current, optionally an instruction, and uses a metered model. Set is free. Read history with studio_description. |
set_art_direction | write | Save the Studio art direction after open_session and read_studio. Pass the record's art_direction shape and revision; its options show allowed choices. Free. The API refuses stale revisions. |
suggest_studio_settings | spend | Suggest settings for a shot after open_session and read_studio. Pass the shot key and current revision. Uses a metered model; read the suggestions before saving art direction or the shoot list. |
shoot_list | spend | Set or run the shoot list after open_session and read_studio. Set passes shots with shot, optional direction (setting, actor, backdrop, note), phase and component. Use revision and expected_list_revision from the record. Set is free; run queues metered images; retry runs again only the shots of the last run that produced no picture. Reuse idempotency_key for a retry; poll studio_run_status. |
set_studio_role | write | Seat a reviewed candidate in a Studio role after open_session and read_studio. Pass role and candidate_id from that record. Free; stale, cross-scope or unapproved selections retain the API's refusal. |
Scenario Director setup, plans, runs, questions and evidence. On the main address only.
| Tool | Scope | What it does |
|---|---|---|
director_questions | read | List the scenario's Director questions after open_session. Free. Use ask_director_question to record an ask for a selected run and step. |
ask_director_question | spend | Record a Director question ask after open_session and director_questions. Needs run_id and step_id; may include question_key or custom_question_id from the list, and returns its occurrence. Recording an occurrence is free; continuing the Director's answer work is metered. Does not accept an answer or resume a run. To supply missing inventor input use director_control(answer) with objectives {question, text}; respond only resumes and never supplies an answer. Reuse the returned idempotency_key on retries, or supply one before the first ask. |
director_run_status | read | Read one run after Director approval. With no run_id, uses the newest active run, or the latest finished run; returns run:null when none exists. Free. wait_s caps at 45 seconds, polling every two seconds with status, loop and step progress. Stops on waiting_for_input, paused, review_ready or any status outside queued/running/pause_requested/cancel_requested. A bounded wait keeps the API status and adds wait_exhausted. Read the parked reason; Studio work wakes the run through its checkpoint, or director_control(resume) resumes it when permitted. Never treat a parked run as completed. The compact response keeps limits, outcome, required input and actions; read_director section=run pages details omitted from this view. |
director_control | spend | Control the run_id and revision returned by read_director or director_run_status. pause and cancel_to_manual stop work without a model call; resume, restart, reset_objectives and permitted review actions can queue metered work. stop/cancel mean cancel_to_manual; respond means resume. Review actions are review_decision, accept_assessment, explore_aspect and consider_reframing, with their API objectives object. Run settings also travel in objectives: step_mode {enabled} stops after each loop; add_allowance {max_loops, new_research, time_seconds} adds increments within the plan's maximum; steer {criterion_id} (null clears) picks the criterion the next route works on; skip_route {route_id} skips the current route; answer {question, text} answers a question the run is waiting on. Reuse command_id for retries. API transition and revision refusals pass through. |
director_apply | spend | Apply reviewed Director candidates after review_ready and read_director_evidence. Pass run_revision and only the selected_candidates you accept, including reviewed Studio candidates in supervised mode. Can start metered work. Preserve the returned idempotency_key when retrying; supply one before the first call to recover a lost response. API source/revision/Studio refusals pass through; an accepted command does not prove downstream assets are finished. |
read_director_evidence | read | Read the Director run's evidence before accepting candidates. Needs open_session, scenario_id and run_id from read_director. Free; returns the page and cursor unchanged. Follow the returned cursor to read further pages; default limit is 50. |
read_director | read | Read bounded Director state after open_session. Default summary shows saved setup revisions, plan/run summaries, account limits and the application URL. Sections setup, criteria, sources, capabilities, plan and run expose exact API data as paged fields. plan/run need their saved ID; plans/runs page history. Follow $detail.path using the same section and ID. next_cursor continues the same path; string cursors are character offsets. No data is silently truncated. Free; keep returned revisions and reread before changing them. |
director_criteria | spend | Save or suggest completion criteria after read_director. Save is free and needs the criteria draft revision, initially 0. Suggest runs a metered model and also needs current scenario_revision and idea_revision. Pass criteria objects and rejected_ids when saving; API revision refusals are unchanged. Use criterion_id to regenerate one criterion and command_id to identify a retry. |
director_plan | spend | Create a Director draft from a goal, or approve a reviewed plan_id and revision. Needs open_session and an existing scenario; read_director shows limits. Create is free; approval starts the first loop and metered work. Save criteria first or pass success_criteria; missing criteria use the saved, non-rejected draft. An empty draft retains the API's success_criteria_required refusal. Missing theme/frame snapshots come from the scenario. Missing question_program uses current catalog and custom questions in API order, capped by its max_questions; pass your own program or an empty list to choose explicitly. Review the returned draft before approval. Use supervised mode to review candidates before applying them. When setup_revision is supplied, the saved setup is authoritative and no question-bank or snapshot defaults are manufactured. Supply command_id before the first create/approve to recover a lost response; reuse it only for the same request. A key is returned if omitted. Objective, sources, approach, limits, outputs and studio retain the API's structured controls and cost bounds. A studio set names each output by type, or by type:slug for a phase or part variant such as sequence_strip:teardown, with that variant's phase or component in controls keyed by the same id. |
director_setup | spend | Save Director setup or prepare its selected sources after read_director. Use the setup revision and retain command_id for a retry; one is returned when omitted. Save is free and accepts the named setup step and structured settings. prepare_sources may enqueue metered reading; criterion_id narrows that work. Read the returned preparation state before proceeding to plan creation. |
Public examples on ipguru.ai. For IPGuru administrators who own the scenario. On the main address only.
| Tool | Scope | What it does |
|---|---|---|
read_publication | read | Inspect saved publication status and capability, free, administrator owner only. section selects status, draft, inventory, preparation, editions or audiences. Large sections are JSON text pages; follow next_offset with view_digest to detect changes. status includes the confirmed live edition and URL; it does not imply the pending update is live. No models run. Preparation progress is persisted; read again to poll without keeping this client connected. |
configure_publication | write | Save a public-example selection at its current expected_revision. Select only the material the user wants public. Free; does not prepare or publish. advance_original defaults false: enable only when further development was requested. Read the returned revision before the next mutation; after a lost response inspect the saved draft rather than blindly writing again. |
prepare_publication | spend | Start durable, metered public-edition preparation from the saved selection. Supply expected_revision and a stable idempotency_key before the first call; reuse that key after a lost response. Poll read_publication(preparation). This commissions work and does not publish or approve a public edition. |
continue_publication_preparation | spend | Resume or retry the existing preparation at its saved revision. May resume metered work; does not publish. Read current preparation state/revision after a lost response before issuing another control. |
stop_publication_preparation | write | Pause or cancel only this public-edition preparation at its saved revision. No new model work. Existing completed artifacts and any live edition remain. Read preparation state after a lost response before repeating. |
preview_publication | write | Freeze the selected public edition for review. Free; does not publish. Returns preview_id and candidate edition_id/digest bound to exact bytes. Review its file list and read_publication_asset, obtain the user's explicit decision, then publish with the returned identities. Changed source or selection requires a fresh preview. After a lost response inspect editions and make a fresh preview; never guess an approval identity. |
publish_publication | write | After the user approves the exact frozen edition, apply its preview_id, edition_id and digest with a caller-stable idempotency_key. Pass the reviewed selection and current revision, without adding unreviewed material. Free; queues publication and returns persisted status, not a success claim. Poll read_publication until live_edition_id matches this edition and status is published. A failed update preserves the prior live edition. |
retry_publication | write | Retry the existing failed publish/withdraw journal at its current revision. Free; reuses the reviewed edition and does not regenerate or approve new material. Poll status; inspect state after a lost response before repeating. |
preview_publication_withdrawal | write | Create the required withdrawal preview. Free; no withdrawal yet. Review the consequence with the user, then pass preview_id to withdraw_publication. Previously completed recipient copies are retained. |
withdraw_publication | write | Withdraw after the user's decision using the withdrawal preview_id and a caller-stable idempotency_key. Free; retains completed recipient copies. Poll persisted publication status to confirm withdrawal; reuse the same key after a lost response. |
read_publication_asset | read | Read exact private frozen edition bytes by key from its file list. Free. Returns bounded base64 chunks, total bytes and SHA-256; follow next_offset to read the whole file. Authentication/owner checks run on every chunk. The authenticated URL contains no token and is not a public preview copy. |
Errors
IPGuru passes the app's own messages through unchanged, so they can be shown to the member as they are.
| Answer | Meaning |
|---|---|
| HTTP 401 | No token, or the connection was revoked or expired. Sign in again. |
scope_required | The connection lacks the scope this tool needs. |
| A rate-limit error | Too many requests on this connection. Slow down and try again. |
| A conflict or stale revision | The record changed since the client read it. |
| An allowance or membership refusal | The member's membership does not cover the action. Do not retry. |
| An unknown session | Call open_session again. |
| This connector call could not be recorded | IPGuru could not record the call, so it did not start it. Try again later. |
This page describes connector version 0.9.0. Questions: contact us.