Build on Studio
Make decks, pages and HTML pages from code or an agent. Create them from blocks and charts, change one slide or block by id, keep versions, and share by link over MCP and REST.
An artifact is data: a deck is a list of slides, a page is a list of blocks, and Venom draws them with the organisation's theme. Your code or agent sends compact specs and small edits instead of HTML. See Studio for the product and Blocks and charts for the component library.
What you can build
- A report generator. Create a page with a heading, a
statsrow and a few charts from your own data, then hand the user theurl. - A deck an agent iterates on. Create the outline once, then change a slide at a time with
studio_content_edit. Each call is a few lines, and each write is a version the user can go back to. - A public one-pager. Create a page, then
studio_share_createfor a link anyone can open, andstudio_share_revokewhen it has done its job. - An HTML dashboard. For what blocks cannot say, an
htmlartifact: your own markup, shown sandboxed with no network.
At a glance
Generated from the code on every docs build.
| MCP endpoint | https://cloud.usevenom.dev/workspace/mcp/studio, server name venom-studio |
| Connect | claude mcp add --transport http venom-studio https://cloud.usevenom.dev/workspace/mcp/studio |
| MCP tools | 30 (15 read, 15 write) |
| OAuth scopes | studio:read studio:write |
| REST twin | 31 routes under https://cloud.usevenom.dev/api/v1 |
| Webhook events | none yet |
Authentication and scopes
- A personal API key or an OAuth grant acts as the member, with their org role's rights. OAuth apps need
studio:readfor the read tools andstudio:writefor the rest. - A team key bound to a service agent, or a key naming an agent with
x-venom-agent, acts as that agent and owns what it makes. - A team key with no agent only reads what the organisation shares.
Artifacts are private until their owner sets visibility to a team or the org, or creates a public link. An artifact the caller may not see is "No such artifact", the same as a missing one.
Worked example
Create a one-slide deck and then change its title by id. $VENOM_KEY is a personal key.
curl -X POST "$VENOM_CLOUD/api/v1/studio/artifacts" \
-H "Authorization: Bearer $VENOM_KEY" -H 'Content-Type: application/json' -H 'Idempotency-Key: q3-review-1' \
-d '{"kind": "deck", "title": "Q3 review", "content": {"slides": [
{"id": "intro", "layout": "title", "content": {"title": "Q3 review", "subtitle": "Growth and margin"}}]}}'The answer has the artifact's id, url, version and the ids it made. Then:
curl -X POST "$VENOM_CLOUD/api/v1/studio/artifacts/$ID/edit" \
-H "Authorization: Bearer $VENOM_KEY" -H 'Content-Type: application/json' -H 'If-Match: "1"' \
-d '{"ops": [{"op": "slide.patch", "id": "intro", "content": {"subtitle": "Growth, margin, next steps"}}]}'A stale If-Match is a 412 version_conflict with the current version in the message. A bad spec is a 422 whose message lists
every problem with its path and the allowed values.
REST routes
The REST twin: 31 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/studio/catalog |
The block types and slide layouts | studio_catalog_get |
| GET | /api/v1/studio/components |
The schema and an example of block types | studio_component_get |
| GET | /api/v1/studio/layouts |
The slide layouts | studio_layout_get |
| GET | /api/v1/studio/themes |
The built-in and the org's themes, or one in full | studio_theme_list |
| PUT | /api/v1/studio/themes/{id} |
Create, change or delete an org theme, or make it the default | studio_theme_set |
| POST | /api/v1/studio/theme-import |
Propose a theme from a design system's files, or save it | studio_theme_import |
| GET | /api/v1/studio/marks |
The organisation's default marks | studio_marks_get |
| PUT | /api/v1/studio/marks |
Set the organisation's default marks (header, footer, company, logo, author, date, label, numbers) | studio_marks_set |
| GET | /api/v1/studio/artifacts |
List decks, pages and html pages | studio_artifact_list |
| POST | /api/v1/studio/artifacts |
Create a deck, a page or an html page | studio_artifact_create |
| GET | /api/v1/studio/artifacts/search |
Search artifacts by title and text | studio_artifact_search |
| POST | /api/v1/studio/artifacts/validate |
Dry-run content, html or ops without saving | studio_artifact_validate |
| GET | /api/v1/studio/artifacts/{id} |
Read an artifact (meta, outline or content) | studio_artifact_get |
| PATCH | /api/v1/studio/artifacts/{id} |
Change title, theme, tweaks, marks or sharing | studio_artifact_update |
| POST | /api/v1/studio/artifacts/{id}/delete |
Move an artifact to the trash | studio_artifact_delete |
| POST | /api/v1/studio/artifacts/{id}/restore |
Bring a deleted artifact back | studio_artifact_restore |
| POST | /api/v1/studio/artifacts/{id}/duplicate |
Copy an artifact | studio_artifact_duplicate |
| GET | /api/v1/studio/artifacts/{id}/outline |
Ids and titles of an artifact's slides or blocks | studio_outline_get |
| POST | /api/v1/studio/artifacts/{id}/edit |
Edit slides or blocks by id (a batch of ops), or replace the content | studio_content_edit |
| POST | /api/v1/studio/artifacts/{id}/html |
Edit an html page with anchored string edits | studio_html_edit |
| GET | /api/v1/studio/artifacts/{id}/export |
Export as json, markdown, outline, html, pptx or print (the print view and its document) | studio_artifact_export |
| GET | /api/v1/studio/artifacts/{id}/preview |
Preview links and a text summary | studio_preview_get |
| GET | /api/v1/studio/artifacts/{id}/versions |
An artifact's versions | studio_version_list |
| POST | /api/v1/studio/artifacts/{id}/versions/{version}/restore |
Make an earlier version current | studio_version_restore |
| GET | /api/v1/studio/artifacts/{id}/shares |
An artifact's public links | studio_share_list |
| POST | /api/v1/studio/artifacts/{id}/shares |
Create a public link | studio_share_create |
| POST | /api/v1/studio/artifacts/{id}/shares/revoke |
Revoke one public link or all | studio_share_revoke |
| GET | /api/v1/studio/research |
Your recent research runs | studio_research_get |
| POST | /api/v1/studio/research |
Start a research run: plan, research, analysis, build and review of a researched report | studio_research_start |
| GET | /api/v1/studio/research/{id} |
A research run's plan card: goals, steps, researchers, sources, the artifact | studio_research_get |
| POST | /api/v1/studio/research/{id}/cancel |
Cancel a research run | studio_research_cancel |
MCP tools
30 tools: 15 read, 15 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.
| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
studio_artifact_create |
Create an artifact | write | studio:write |
POST /api/v1/studio/artifacts |
studio_artifact_delete |
Delete an artifact | write (destructive) | studio:write |
POST /api/v1/studio/artifacts/{id}/delete |
studio_artifact_duplicate |
Duplicate an artifact | write | studio:write |
POST /api/v1/studio/artifacts/{id}/duplicate |
studio_artifact_export |
Export an artifact | read | studio:read |
GET /api/v1/studio/artifacts/{id}/export |
studio_artifact_get |
Read an artifact | read | studio:read |
GET /api/v1/studio/artifacts/{id} |
studio_artifact_list |
List artifacts | read | studio:read |
GET /api/v1/studio/artifacts |
studio_artifact_restore |
Restore a deleted artifact | write | studio:write |
POST /api/v1/studio/artifacts/{id}/restore |
studio_artifact_search |
Search artifacts | read | studio:read |
GET /api/v1/studio/artifacts/search |
studio_artifact_update |
Rename, retheme, tweak, mark or share | write | studio:write |
PATCH /api/v1/studio/artifacts/{id} |
studio_artifact_validate |
Dry-run a spec | read | studio:read |
POST /api/v1/studio/artifacts/validate |
studio_catalog_get |
List the component library | read | studio:read |
GET /api/v1/studio/catalog |
studio_component_get |
Get a block's spec | read | studio:read |
GET /api/v1/studio/components |
studio_content_edit |
Edit slides or blocks by id | write | studio:write |
POST /api/v1/studio/artifacts/{id}/edit |
studio_html_edit |
Edit an html page | write | studio:write |
POST /api/v1/studio/artifacts/{id}/html |
studio_layout_get |
List slide layouts | read | studio:read |
GET /api/v1/studio/layouts |
studio_marks_get |
Read the org's default marks | read | studio:read |
GET /api/v1/studio/marks |
studio_marks_set |
Set the org's default marks | write | studio:write |
PUT /api/v1/studio/marks |
studio_outline_get |
Read an outline (cheap) | read | studio:read |
GET /api/v1/studio/artifacts/{id}/outline |
studio_preview_get |
Preview links and a text summary | read | studio:read |
GET /api/v1/studio/artifacts/{id}/preview |
studio_research_cancel |
Cancel a research run | write (destructive) | studio:write |
POST /api/v1/studio/research/{id}/cancel |
studio_research_get |
Read a research run | read | studio:read |
GET /api/v1/studio/research (+1) |
studio_research_start |
Start a research run | write | studio:write |
POST /api/v1/studio/research |
studio_share_create |
Create a public link | write | studio:write |
POST /api/v1/studio/artifacts/{id}/shares |
studio_share_list |
List public links | read | studio:read |
GET /api/v1/studio/artifacts/{id}/shares |
studio_share_revoke |
Revoke a public link | write (destructive) | studio:write |
POST /api/v1/studio/artifacts/{id}/shares/revoke |
studio_theme_import |
Propose a theme from a design system | write | studio:write |
POST /api/v1/studio/theme-import |
studio_theme_list |
List themes | read | studio:read |
GET /api/v1/studio/themes |
studio_theme_set |
Create, change or delete a theme | write | studio:write |
PUT /api/v1/studio/themes/{id} |
studio_version_list |
List versions | read | studio:read |
GET /api/v1/studio/artifacts/{id}/versions |
studio_version_restore |
Restore a version | write | studio:write |
POST /api/v1/studio/artifacts/{id}/versions/{version}/restore |