Skip to content
Docs menu

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.

View .md

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 stats row and a few charts from your own data, then hand the user the url.
  • 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_create for a link anyone can open, and studio_share_revoke when it has done its job.
  • An HTML dashboard. For what blocks cannot say, an html artifact: 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:read for the read tools and studio:write for 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