Also: GET /openapi.summary.json · GET /openapi.json · GET /.well-known/ai-agents.summary.json · GET /.well-known/ai-agents.json · GET /.well-known/context-ops.json · GET /.well-known/agent-install.json · tool-call interoperability · legacy POST /api.
Limits and privacy
On 429 or 503, wait for Retry-After and retry once.
Single run60/min · 8 concurrent · 5sPer-tool limits in each schema.
Batch and pipeline20/min · 3 concurrent · 12sMax five requests or steps.
Utilito does not collect product analytics, and API/MCP responses emit no metrics response header. Raw inputs and outputs are not stored for product analytics. Do not submit secrets, private keys, passwords, regulated data, or sensitive personal information.
Each exact recipe targets one canonical envelope: a single request uses { tool_id, input, response_mode? }; a batch contains 1–5 independent requests with unique caller IDs; and a pipeline contains 1–5 allowlisted steps with only $INPUT, $PREV, or past-only $STEP[n] bindings.
Selection does not compile automatically. An explicit Compile request action creates JSON and TypeScript request files locally. The catalog does not run or submit requests, store inputs, add browser history, or collect product analytics.
Endpoints
GET /apiHealth + router overview.
GET /api/toolsCompact tool list.
GET /api/tools/search?q=json+csvSearch tools.
GET /api/tools/:id/schemaOne schema + limits.
POST /api/runRun one tool.
POST /api/batchUp to five independent requests.
POST /api/pipelineUp to five linked steps.
POST /apiLegacy run.
GET /openapi.jsonOpenAPI 3.1.
GET /.well-known/context-ops.jsonFive Context Ops workflows.
GET /.well-known/ai-agents.jsonAgent discovery catalog.
GET /.well-known/agent-install.jsonHosted MCP install profiles.
Product Kits package current Utilito tools into complete jobs with strict inputs, generated client code, executable examples, typed failures, and redacted receipts.
Integration Launch Kitintegration-launch-kitGo from client setup to one schema-checked, verified Utilito call. Open the runnable kit.
Structured Output Recovery Kitstructured-output-recovery-kitTurn malformed JSON or tool output into canonical JSON with validation evidence and a safe retry action. Open the runnable kit.
CI Failure Review Kitci-failure-review-kitTurn one bounded CI failure log into line-addressable evidence, submitted patch status, a safe report, and an agent-ready context pack. Open the runnable kit.
Evaluation Dataset QA Kitevaluation-dataset-qa-kitPreflight one bounded evaluation dataset and compare submitted candidate and baseline outputs with deterministic exact-match evidence. Open the runnable kit.
RAG Evidence Preparation Kitrag-evidence-preparation-kitTurn already-retrieved records into bounded citation-ready evidence with exact quotes and explicit omissions. Open the runnable kit.
Contract Release Gate Kitcontract-release-gate-kitGate one bounded JSON Schema, tool contract, or OpenAPI operation release with direction-aware compatibility and fixture evidence. Open the runnable kit.
Data Migration Prep Kitdata-migration-prep-kitPrepare explicitly mapped structured data for a manual import with safe exports, rejected-row evidence, and integrity digests. Open the runnable kit.
Agent Run Forensics & Handoff Kitagent-run-forensics-handoff-kitTurn a failed or paused agent run into a redacted deterministic timeline, conservative retry review, and manual handoff artifacts. Open the runnable kit.
Web Release QA Kitweb-release-qa-kitCombine submitted local web QA evidence into a truthful deterministic pass, block, or unknown release matrix. Open the runnable kit.
Finance Scenario Memo Kitfinance-scenario-memo-kitCompare two to five explicit finance scenarios in one family and export a deterministic review memo. Open the runnable kit.
LLM Provider Message Migration Kitprovider-message-migration-kitConvert submitted message and tool-call fixtures between OpenAI, Anthropic, Gemini, and canonical Utilito shapes without a model rewrite. Open the runnable kit.
Tool Schema Publishing Kittool-schema-publishing-kitPublish one strict tool contract into deterministic provider definitions, executable fixtures, assertions, OpenAPI, and documentation. Open the runnable kit.
Webhook Normalization Kitwebhook-normalization-kitNormalize submitted webhook fixtures into one strict canonical event contract with explicit mappings, reviewable rejections, and handler artifacts. Open the runnable kit.
Configuration Migration Kitconfiguration-migration-kitConvert one bounded JSON, YAML, TOML, or env configuration with explicit type, omission, rename, and secret-handling evidence. Open the runnable kit.
Prompt Regression Kitprompt-regression-kitCompare bounded prompt templates with explicit variables, literal fixtures, estimated context and cost assumptions, and deterministic release rules. Open the runnable kit.
API Migration Kitapi-migration-kitTurn one bounded schema or selected inline OpenAPI operation change into explicit payload, client, fixture, and caller migration artifacts. Open the runnable kit.
Release Evidence Kitrelease-evidence-kitCombine submitted checks, artifact integrity metadata, limitations, rollback notes, and evidence references into one deterministic release packet. Open the runnable kit.
Accessibility Remediation Kitaccessibility-remediation-kitTurn submitted accessibility findings and browser-local HTML into prioritized remediation tasks, contrast alternatives, and regression assertions without a false compliance claim. Open the runnable kit.
Image Delivery Production Kitimage-delivery-production-kitTurn one browser-local image into bounded responsive variants, accurate srcset markup, integrity metadata, and a truthful pixel-memory delivery receipt. Open the runnable kit.
PDF Deliverable Assembly Kitpdf-deliverable-assembly-kitCombine, reorder, rotate, omit, and label pages from local PDFs into one verified deliverable and exact assembly manifest. Open the runnable kit.
Agent Connection Diagnostic Kitagent-connection-diagnostic-kitDiagnose a sanitized MCP or agent client configuration and submitted connection transcript offline without opening a connection. Open the runnable kit.
Agent Tool-Call Replay Kitagent-tool-call-replay-kitValidate one submitted tool-call trace and package an inert deterministic replay fixture without executing any tool. Open the runnable kit.
Context Budget Planning Kitcontext-budget-planning-kitAllocate whole submitted content records against an explicit context budget and estimate cost without inspecting, reflecting, ranking, or rewriting content. Open the runnable kit.
HTTP Security Remediation Kithttp-security-remediation-kitTurn submitted HTTP headers and optional local HTML metadata into sanitized security findings, reviewable header candidates, assertions, and a remediation report. Open the runnable kit.
Offline API Batch Production Kitoffline-api-batch-production-kitGenerate fixed-origin curl, JavaScript, and Python production artifacts for one validated Utilito API batch without executing it. Open the runnable kit.
Large Payload Reduction Kitlarge-payload-reduction-kitReduce explicitly selected JSON, JSONL, text, or log content into a bounded whole-unit artifact with exact omission evidence. Open the runnable kit.
Mermaid Diagram Delivery Kitmermaid-diagram-delivery-kitValidate one bounded Mermaid flowchart and generate accessible SVG plus optional PNG entirely in the browser with actual-byte integrity receipts. Open the runnable kit.
File Verification Handoff Kitfile-verification-handoff-kitCompare selected browser-local files with a strict integrity manifest and create an exact verification handoff packet without uploading file bytes. Open the runnable kit.
Image Delivery Audit Kitimage-delivery-audit-kitAudit one browser-local image and submitted delivery metadata for responsive coverage, decoded memory, bandwidth assumptions, and render risks without changing the image. Open the runnable kit.
Product Contract Review Kitproduct-contract-review-kitReview one submitted deterministic product contract for schema, sample, limit, claim, privacy, provenance, and API/MCP consistency. Open the runnable kit.
The Integration Launch Kit supports exactly the five canonical hosted client profiles above and JavaScript, TypeScript, Python, or curl. It always uses the fixed hosted endpoint, loads one selected schema, and verifies one real deterministic call. Arbitrary endpoints, headers, authentication values, credential storage, and Local MCP publication are outside this contract.
Context Ops recipes
Start with the job. Each request is generated from shared recipe data and exercised by the same deterministic cores used by the API. Exact bytes are measured; clearly labeled token estimates are conservative and are not provider-tokenizer guarantees. Agents can fetch the same five workflows from /.well-known/context-ops.json.
Malformed model output
Repair malformed JSON
Recover a parseable object and inspect deterministic repairs; use Structured Output Rescue when canonicalization, schema checks, or tool-call validation are also required.
{
"tool_id": "json-query",
"response_mode": "compact",
"input": {
"input": "{\"users\":[{\"id\":1,\"name\":\"User 1\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":2,\"name\":\"User 2\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":3,\"name\":\"User 3\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":4,\"name\":\"User 4\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":5,\"name\":\"User 5\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":6,\"name\":\"User 6\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":7,\"name\":\"User 7\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":8,\"name\":\"User 8\",\"status\":\"active\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":9,\"name\":\"User 9\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":10,\"name\":\"User 10\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":11,\"name\":\"User 11\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":12,\"name\":\"User 12\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}}]}",
"query": "users.7"
}
}
Unknown large structure
Shrink with explicit markers
Keep representative values and make every truncation visible in-band; use Context Distill for hard byte caps, field projection, stable dedupe, and error neighborhoods.
Start in the browser-local flagship for strict transforms, literal log reduction, or bounded local-file selection; this optional hosted request accepts only the CSV text explicitly submitted.
{
"response_mode": "compact",
"requests": [
{
"id": "repair",
"tool_id": "structured-output-recovery-kit",
"response_mode": "full",
"input": {
"text": "{name:\"Ada\",items:[1,2,],}",
"recovery_policy": "conservative"
}
},
{
"id": "extract",
"tool_id": "json-query",
"response_mode": "compact",
"input": {
"input": "{\"users\":[{\"id\":1,\"name\":\"User 1\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":2,\"name\":\"User 2\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":3,\"name\":\"User 3\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":4,\"name\":\"User 4\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":5,\"name\":\"User 5\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":6,\"name\":\"User 6\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":7,\"name\":\"User 7\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":8,\"name\":\"User 8\",\"status\":\"active\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":9,\"name\":\"User 9\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":10,\"name\":\"User 10\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":11,\"name\":\"User 11\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}},{\"id\":12,\"name\":\"User 12\",\"status\":\"inactive\",\"profile\":{\"bio\":\"Profile metadata that is not needed by the agent.\"}}]}",
"query": "users.7"
}
}
]
}
Linked transformation
Compose without intermediates
Run three deterministic steps server-side and return only the final output plus a bounded trace.
{
"input": "{users:[{name:\"Ada\",bio:\"A long biography that should be bounded before model context\"},{name:\"Lin\",bio:\"Another long biography that should be bounded before model context\"},],}",
"steps": [
{
"tool_id": "json-repair",
"input": {
"input": "$INPUT"
}
},
{
"tool_id": "json-query",
"input": {
"input": "$PREV",
"query": "users.*"
}
},
{
"tool_id": "json-shrink",
"input": {
"input": "$PREV",
"max_array_items": 1,
"max_string_length": 48
}
}
]
}
Do not send secrets or regulated data. Browser-local pages remain the safer front door for sensitive one-off work.
Offline batch / pipeline builder
Offline API Batch Builder
Validate and export 1 to 5 existing Utilito API requests without executing or replaying them. Independent requests export to /api/batch; past-step bindings export to /api/pipeline.
Bindings:$INPUT, $PREV, and exact $STEP[n] references to completed earlier steps only.
This builder is browser-local and performs no network requests. Inputs are submitted to Utilito only if you deliberately run the exported curl or JSON request. For one interactive first call, use the API playground. Do not put secrets or regulated data in API payloads.
Batch and pipeline examples
Batch runs up to five independent deterministic requests. Each needs a unique id (1–80 characters).
Pipeline chains up to five allow-listed steps. Output of each step binds as $PREV. Omitting input auto-pipes the previous output, so {"query":"name"} means {"input":"$PREV","query":"name"}.
Keep an explicit input when step contracts differ. Pipeline intermediates are never returned to the caller.
Agent discovery & integration checklist
Agents that need a cheap catalog can fetch GET /.well-known/ai-agents.json instead of scraping pages or loading full OpenAPI.
Discover/.well-known/ai-agents.jsonPick a candidate by id, category, keyword, or description.
Inspect/api/tools/:id/schemaLoad the schema if the summary is not enough.
RunPOST /api/runSend the manifest’s api.tool_id and receive the same stable envelope.
The manifest is a routing index, not a promise that raw inputs are safe to send. Browser-local tools remain safer for secrets, passwords, private keys, regulated data, and sensitive personal information.
Agent integration checklist
Validate the OpenAPI contractGET /openapi.jsonCheck OpenAPI 3.1 metadata, x-utilito-router-flow, required paths, and tool schemas before pinning an integration.
Use manifest hints/.well-known/ai-agents.jsonPrefer the manifest for routing, examples, privacy modes, and tool ids.
Keep execution boundedPOST /api/runRun one deterministic utility per request and surface UNKNOWN_TOOL or validation errors to the operator.
Deterministic run example
# One deterministic API-run request
curl -X POST https://utilito.dev/api/run \
-H "Content-Type: application/json" \
-d '{"tool_id":"token-counter","input":{"text":"Summarize this prompt before sending it to an agent."}}'
# Contract metadata for agent clients
curl https://utilito.dev/openapi.json | jq '.info.title, .["x-utilito-router-flow"]'
Utilito does not make live LLM calls from these API tools. Inputs submitted to server endpoints are processed by deterministic shared cores and should still exclude secrets or regulated data.
Contract Ops API/MCP contract
Contract Ops exposes three separate contracts: contract-reliability-workbench for portfolios of related contracts and submitted fixtures; contract-release-gate-kit for one-contract release gates; and agent-contract-check for lightweight schema and argument checks.
Portfolio reliabilitycontract-reliability-workbench · 1–5 contracts · 0–100 fixturesDirection-aware matrices, cross-contract references, fixture coverage, unknowns, assertions, and exact receipts with no network reference resolution or execution.
One-contract release gatecontract-release-gate-kitPreserves the existing one-contract fixture, report, and assertion contract.
One contract checkagent-contract-checkCompare saved and current schemas, validate one argument object, inspect bounded retry safety, and receive one deterministic report without executing the described tool.
Stable identity64-char fixture id · 512-char hintSupply a safe fixture id or use the deterministic schema-derived id. Review hints are bounded and never generated by an LLM.
Typed review resultAGENT_CONTRACT_CHECK_FAILEDSchema drift, argument diagnostics, or unsafe retry state returns a typed deterministic result.
# One schema and tool-call check through the canonical API router
curl -X POST https://utilito.dev/api/run \
-H "Content-Type: application/json" \
-d '{"tool_id":"agent-contract-check","input":{"fixture_id":"lookup-user-v1","saved_schema":{"type":"object","properties":{"user_id":{"type":"string"}}},"current_schema":{"type":"object","properties":{"user_id":{"type":"string"}}},"arguments":{"user_id":"u_123"}}}'
# Or call the same tool through MCP run_tool
{"name":"run_tool","arguments":{"tool_id":"agent-contract-check","input":{"saved_schema":{"type":"object"},"current_schema":{"type":"object"},"arguments":{}},"response_mode":"compact"}}
Browser-local work is safer for sensitive one-off contracts. Server-submitted schemas, arguments, and results are response-only and are not stored or indefinitely retained for Contract Ops. No schedules, stored fixtures, webhooks, or recurring monitoring. Request a named contract workflow when one-shot validation is not enough.
Agent Context Handoff API/MCP contract
Agent Context Handoff runs agent-context-handoff over one strict caller-submitted document and emits a bounded dependency-closed Context Pack, Markdown evidence report, integrity manifest, inert next-agent prompt, and exact omission receipt.
Submitted evidence onlyutilito.agent-handoff.v1Decisions, completed work, blockers, actions, artifacts, evidence, unknowns, constraints, and notes remain distinct whole records.
Integrity boundarycaller_submitted_unverifiedSubmitted digests are preserved but never recomputed; only derived output artifacts receive locally computed hashes.
Bounded output1,024–65,536 Context Pack bytesDependency closure and omission IDs remain explicit without invented summaries or partial records.
Context Pack and evidence report API/MCP contract
Context Workbench builds bounded model-ready packs across API, CI, RAG, handoff, contract, evaluation, failure, accessibility, patch, log, data-quality, HTTP-security, and file-integrity jobs; Artifact Ops turns the same typed pack into Markdown or standalone HTML. Both browser previews run locally. Server calls are response-only and use deterministic cores with no model call or report storage. No model summary is generated; a transformation receipt does not prove the submitted state is true.
Review product families: Contract, Evaluation Fixture, Agent Run Failure, Accessibility Review, Patch Verification, Log Triage, Structured Data Quality, HTTP Security, and File Integrity Change all use the same bounded Context Pack and Evidence Report envelopes.
Context Pack Buildercontext-pack-builderReview recipes include contract, evaluation fixture, agent-run failure, accessibility, patch verification, log triage, structured-data quality, HTTP security, and file-integrity change alongside API, CI, RAG, and handoff jobs. Output plus retained evidence is bounded to 1,000,000 bytes.
Evidence Report Builderevidence-report-builderEach review recipe has a matching report preset. Exports are escaped markdown or standalone html; 256,000-byte input and 500,000-byte output.
Full envelope requiredresponse_mode: fullCompact/output modes are rejected for these two tools so schema, evidence, receipt, provenance, and typed errors remain intact. Use two separate calls: CA2 is not supported by /api/pipeline or MCP run_pipeline.
Bounded artifactutilito.evidence-report.v1HTML uses fixed Utilito CSS and escaped text only. No arbitrary HTML input, scripts, forms, remote resources, PDF, screenshots, public hosting, or storage.
# Build a CI failure Context Pack and keep the typed result
PACK=$(curl -sS -X POST https://utilito.dev/api/run \
-H "Content-Type: application/json" \
-d '{"tool_id":"context-pack-builder","response_mode":"full","input":{"recipe":"ci-failure-pack","input":"start\nERROR build failed\nstack","max_bytes":4096}}' | jq -c '.result')
# Submit that exact result in a separate report call
jq -n --argjson pack "$PACK" '{tool_id:"evidence-report-builder",response_mode:"full",input:{context_pack:$pack,preset:"ci-incident-report",export_format:"markdown"}}' \
| curl -sS -X POST https://utilito.dev/api/run -H "Content-Type: application/json" --data-binary @-
# Build a strict agent handoff, then render it without another model call
HANDOFF=$(jq -n '{schema_version:"utilito.agent-handoff.v1",handoff_id:"review-1",goal:"Move verified work to the next agent",status:"ready_for_review",decisions:[],completed:[],blockers:[],next_actions:[{id:"action-1",summary:"Run review",priority:"high",depends_on:[]}],artifacts:[],evidence:[],notes:[]}')
PACK=$(jq -n --argjson handoff "$HANDOFF" '{tool_id:"context-pack-builder",response_mode:"full",input:{recipe:"agent-handoff-pack",input:$handoff,max_bytes:8192}}' \
| curl -sS -X POST https://utilito.dev/api/run -H "Content-Type: application/json" --data-binary @- | jq -c '.result')
jq -n --argjson pack "$PACK" '{tool_id:"evidence-report-builder",response_mode:"full",input:{context_pack:$pack,preset:"agent-handoff-report",export_format:"markdown"}}' \
| curl -sS -X POST https://utilito.dev/api/run -H "Content-Type: application/json" --data-binary @-
Typed failures include INVALID_HANDOFF_SCHEMA, DUPLICATE_HANDOFF_ID, UNRESOLVED_HANDOFF_REFERENCE, INVALID_CONTRACT_REVIEW_SCHEMA, CONTRACT_REVIEW_RECEIPT_MISMATCH, INVALID_EVALUATION_FIXTURE_SCHEMA, INVALID_AGENT_RUN_FAILURE_SCHEMA, INVALID_ACCESSIBILITY_REVIEW_SCHEMA, and REVIEW_SUMMARY_MISMATCH. HTTP compact/output requests fail with INVALID_RESPONSE_MODE. The submitted agent-contract-check result remains response-only.
Context Recipe Diagram: pass a validated recipe as recipe to mermaid-renderer. The renderer emits utilito.context-recipe-diagram.v1 provenance and bounded SVG/HTML/PNG without executing steps, fixtures, or argument values.
Report failures include INVALID_CONTEXT_PACK, UNSUPPORTED_REPORT_PRESET, UNSUPPORTED_EXPORT_FORMAT, REPORT_INPUT_TOO_LARGE, REPORT_OUTPUT_TOO_LARGE, TOO_MANY_EVIDENCE_ITEMS, and UNSAFE_REPORT_VALUE.
Rendering API/MCP contract
Artifact Ops packages Mermaid rendering as a bounded Builder module, not a separate subscription or an expansion of the five-tool Context Ops MCP surface. Use mermaid-renderer through POST /api/run or MCP run_tool after loading GET /api/tools/mermaid-renderer/schema. For sensitive one-off diagrams, use the browser-local workbench.
RenderersSVG 0.1.0 · PNG 0.2.0PNG uses utilito-mermaid-renderer-v1-flowchart-png; every successful response discloses its renderer and version.
Allowed diagramsflowchart onlySequence, class, state, ER, gantt, and pie remain validation-only until a later renderer review.
Limits100KB input · 250KB SVG · 1MB PNG · 2,000,000 pixelsPNG also has a 10,000px side and 2000ms local render deadline. The 40-node and 80-edge limits remain fixed.
Exports and costsvg · html · png · tiny/small/standardPNG JSON responses return png_base64 with image/png; response_mode: "output" returns raw PNG bytes. Responses include deterministic cache metadata and cost buckets. Cache metadata describes deterministic cacheability; it is not evidence of persisted artifacts.
# Render a simple flowchart through the canonical API router
curl -X POST https://utilito.dev/api/run \
-H "Content-Type: application/json" \
-d '{"tool_id":"mermaid-renderer","input":{"source":"flowchart TD\n A[Start] --> B[Done]"},"response_mode":"compact"}'
# Request the bounded response-only PNG export
curl -X POST https://utilito.dev/api/run \
-H "Content-Type: application/json" \
-d '{"tool_id":"mermaid-renderer","input":{"source":"flowchart TD\n A --> B","format":"png"},"response_mode":"compact"}'
# Or call the same tool through MCP run_tool
{"name":"run_tool","arguments":{"tool_id":"mermaid-renderer","input":{"source":"flowchart TD\n A --> B"},"response_mode":"compact"}}
The exhaustive rendering failure contract is EMPTY_INPUT, INPUT_TOO_LARGE, UNSUPPORTED_DIAGRAM_TYPE, UNCLOSED_QUOTE, UNCLOSED_DELIMITER, UNEXPECTED_DELIMITER, INVALID_SEQUENCE_STATEMENT, MERMAID_VALIDATION_FAILED, UNSUPPORTED_EXPORT_FORMAT, UNSUPPORTED_RENDER_DIAGRAM, NO_RENDERABLE_FLOWCHART_EDGES, NODE_LIMIT, EDGE_LIMIT, OUTPUT_TOO_LARGE, RENDER_TIMEOUT, UNSAFE_SVG, PNG_DIMENSION_LIMIT, PNG_OUTPUT_TOO_LARGE, and PNG_RENDER_FAILED. The generated OpenAPI document exposes x-utilito-rendering-service with the same limits and typed failure list.
Rendering inputs are submitted to Utilito servers when using API/MCP. Generated artifacts are not stored or indefinitely retained, and raw inputs or outputs are not retained for analytics. Utilito does not collect product analytics or telemetry. Use the browser-local page for sensitive one-off diagrams. Request a named output format when bounded SVG, HTML, and PNG responses are not enough.
Troubleshooting
No tools after configurationreload · inspect .cursor/mcp.jsonConfirm valid JSON, the exact https://utilito.dev/mcp URL, then reload the Cursor window.
UNKNOWN_TOOLsearch_tools → get_tool_schemaRediscover the current id and load its schema before running it.
RATE_LIMITED · 429Retry-AfterWait for the returned interval. Retry once; do not loop.
SERVICE_BUSY · 503Retry-AfterReduce concurrent batch/pipeline work, wait, and retry once.
Validation or payload errortyped error · limitsUse the schema endpoint and keep runs within documented bounds.
MCP still unavailablePOST /api/runUse the direct HTTP fallback to separate client config trouble from service trouble.
Operational notes: never send secrets; load unfamiliar schemas first; preserve typed errors; and include only error code, status, latency, and client type when reporting friction—never payloads or outputs.