tools/list returns only the tools the presented key's scopes allow. A
key with no write scope cannot see a write tool, let alone call one.
Full argument schemas come back from tools/list itself.
No scope required
| Tool | What it does |
|---|
whoami | Return the identity this API key acts as: your username, display name, plan, and the scopes granted to this key |
read:blueprints
| Tool | What it does |
|---|
get_blueprint | Fetch one of your blueprints by id or slug: prose files plus every diagram tab's components |
get_blueprint_analytics | Aggregate reach for one blueprint you can edit: human views, unique visitors, traffic-source and referrer breakdowns, crawler/AI-agent traffic, and the helpful/not-helpful tally |
get_blueprint_audience | Report who can currently reach a blueprint you can edit: its visibility, its classification label, and whether a password gate is set |
get_blueprint_translation | Fetch one locale's translation: the translated title and summary, plus the per-stratum name/body overlays |
get_portfolio | Fetch one portfolio by id: its metadata, folder tree, and everything filed in it |
get_review_status | Where a blueprint stands in its team's approval gate, and whether submit_for_review would be accepted right now |
get_standalone_diagram | Fetch one standalone diagram in full, including its body |
get_stratum | Fetch one stratum by id: its body plus every secondary tab |
get_template | Fetch one template's metadata and shape: name, description, category, scope, and counts of what the snapshot contains |
list_blueprint_locales | List the languages a blueprint publishes in, with how much of each translation exists |
list_blueprint_tags | List a blueprint's tags, with how each was attached (manual / llm-accepted) and its taxonomy placement |
list_blueprints | List your blueprints, owned and shared with you |
list_change_requests | List the change requests filed against a blueprint you can edit |
list_diagram_tabs | List a blueprint's diagram tabs and the components on each, with ids, kinds and body sizes |
list_icon_packs | List the icon libraries available to you: curated packs, your own uploads, and packs shared by your teams |
list_podium_slides | List every Podium slide on a blueprint, grouped by chapter, with id, label and geometry |
list_portfolios | List your portfolios, with item counts |
list_standalone_diagrams | List standalone diagrams owned by you or by a team/org you belong to |
list_strata | List the strata on a blueprint you can view |
list_templates | List Compendium templates you can see: personal, shared, and Blueprintr defaults |
read:vellums
| Tool | What it does |
|---|
get_vellum | Fetch one vellum diagram in full, including its docYaml body |
list_vellums | List your vellum diagrams: owned, shared via team/org, or granted to you |
read:foliums
| Tool | What it does |
|---|
get_folium | Fetch one folium: metadata, the full page tree (ids, titles, slugs, resolved URL paths, draft status, body sizes) and its strata index |
get_folium_page | Fetch one folium page in full, including its markdown body |
get_folium_stratum | Fetch one folium-owned stratum in full |
list_foliums | List the foliums you can author, newest-edited first |
read:organization
| Tool | What it does |
|---|
get_org | Fetch one organisation you belong to, with your role, aggregate counts and your teams inside it |
get_team | Fetch one team by id or slug. Pair a slug with orgId when two of your orgs use the same one |
list_orgs | List the organisations you belong to, with your role in each |
list_teams | List the teams you belong to, with your role and the organisation each sits under |
search
| Tool | What it does |
|---|
search_my_content | Full-text search across the blueprints and docs you can access |
write:blueprints
| Tool | What it does |
|---|
create_blueprint | Create a new blueprint as a private draft |
create_blueprint_from_template | Create a private draft from a blueprint template you can see |
create_diagram_tab | Add a diagram tab to a blueprint, carrying one component |
create_portfolio | Create a portfolio in a workspace you administer |
create_portfolio_folder | Create a folder inside a portfolio you manage |
create_standalone_diagram | Create a standalone diagram you own |
create_stratum | Add a stratum, optionally bound to a diagram shape so it opens when that shape is clicked |
create_stratum_tab | Add a secondary tab to a stratum |
create_template_from_blueprint | Capture a blueprint as a reusable personal template |
file_blueprint | File a blueprint into a portfolio you manage |
publish_blueprint | Publish one of your standalone draft blueprints |
rename_podium_slide | Change the label of one Podium slide, leaving every other slide untouched |
save_blueprint_translation | Upsert one locale's translation of a blueprint you can edit |
set_blueprint_tags | Replace the whole tag set on a blueprint |
unfile_blueprint | Return a blueprint to its owner's Main portfolio |
update_blueprint | Update one of your draft blueprints: title, summary, and/or body |
update_diagram_component | Replace a diagram component's source (diagram YAML/XML, or markdown for a rich component) |
update_portfolio | Rename a portfolio, or change its description |
update_standalone_diagram | Update a standalone diagram's title and/or body |
update_stratum | Update a stratum's name and/or body |
update_stratum_tab | Update a secondary tab's name and/or body |
update_template_details | Rename a template, or change its description or category |
write:vellums
| Tool | What it does |
|---|
create_template_from_vellum | Capture a vellum as a reusable personal template |
create_vellum | Create a vellum diagram from a docYaml body |
create_vellum_from_template | Create a private vellum from a template you can see |
file_vellum | File a vellum into a portfolio you manage |
unfile_vellum | Return a vellum to the Unfiled bucket |
update_vellum | Update a vellum's title, docYaml body, visibility and/or tags |
write:foliums
| Tool | What it does |
|---|
create_folium | Create a folium with a seed Overview page |
create_folium_page | Add a page to a folium's nav tree |
create_folium_stratum | Add a folium-owned stratum, which is what a stratum: link inside a folium page opens |
move_folium_page | Reparent and/or reorder one page in the nav tree |
update_folium | Update a folium's title and/or description |
update_folium_page | Update a page's title, description, body, icon or nav placement |
update_folium_stratum | Update a folium stratum's name, body, language hint, icon or folder path |
write:sharing
| Tool | What it does |
|---|
raise_blueprint_classification | Raise the classification label: public → internal → confidential |
restrict_blueprint_audience | Make a blueprint less visible: public → unlisted → private |
write:review
| Tool | What it does |
|---|
create_change_request | File a change request against a blueprint you can edit |
submit_for_review | Hand a team-owned draft into its team's approval gate |
withdraw_change_request | Retract an open change request you authored |
The transport is plain JSON-RPC, so you can test without a client:
curl -fsS https://blueprintr.io/api/mcp \
-H "Authorization: Bearer $BLUEPRINTR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"list_blueprints",
"arguments":{"status":"draft","limit":10}}}' \
| jq -r '.result.content[0].text | fromjson'
List tools return a nextCursor. Pass it back as cursor for the next page
rather than raising limit: the ceiling is 100, and paging is cheaper than a
retry.
Up to 20 JSON-RPC messages can go in one batch array. Past that the request is
rejected: a single HTTP request clears the rate limiter once, so an uncapped
batch would fan one request out into arbitrarily many tool calls.
Concurrent writes
update_vellum accepts a baseUpdatedAt. Send the updatedAt you read, and
the write is refused with STALE_WRITE if the document moved underneath you.
Re-read, reapply, retry with the new timestamp.
Without it, the write is last-writer-wins. On a document a person also has
open, send it.
Payload ceilings
| Field | Limit |
|---|
| Blueprint title | 500 characters |
| Blueprint summary | 280 characters |
| Blueprint body | 256 KiB |
Vellum docYaml | 1,500,000 characters |
| Vellum title | 200 characters |
| Vellum tags | 20 tags, 1–64 characters each |
Rate limits
Every window is five minutes.
| Bucket | Limit |
|---|
| Requests per IP | 60 |
| Requests per key | 600 |
| Write tool calls per key | 40 |
| JSON-RPC messages per batch | 20 |
Request-level limits return HTTP 429 and JSON-RPC -32000. The write bucket
returns a tool error asking you to slow down, so it arrives as a normal
result with isError: true rather than as a transport failure.
Errors
| Symptom | What it means |
|---|
Only whoami is listed | The key has no other scope. Scopes are fixed at creation, so mint a new key |
| The documentation tools are listed | The key was not accepted at all. Check the header is complete, and that the key is not revoked |
405 on GET | Expected. The optional SSE stream is not enabled; use POST |
| "Blueprint not found" | Wrong id, or not reachable by this account. Missing and forbidden return the same message, because telling you which would itself be a disclosure |
| A published blueprint will not update | Writes reach your own drafts only |
STALE_WRITE | Someone else changed the vellum. Re-read and retry |
| A vellum body write is refused | Blueprint-bound vellums are edited through the blueprint; a standalone one needs live collaboration switched off first |
429 or -32000 | Poll less, batch smaller |
Tool failures come back as MCP results with isError: true and a readable
message. Only protocol failures use the JSON-RPC error object, so a client
that checks only for error will read a refused write as a success.