---
title: Build on Studio
description: 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.
section: developers
order: 165
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/studio/mcp.ts, services/nodejs-cloud/lib/studio/store.ts, services/nodejs-cloud/lib/mcp/rest.ts]
features: []
---

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](/docs/studio.md) for the
product and [Blocks and charts](/docs/studio/blocks.md) for the component library.

## What you can build {#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 {#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 {#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 {#example}

Create a one-slide deck and then change its title by id. `$VENOM_KEY` is a personal key.

```bash
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:

```bash
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 {#rest}

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](/docs/developers/rest)).

| 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 {#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` |

## Related {#related}

- [Studio](/docs/studio.md), [Edit by id](/docs/studio/edits.md) and [Studio for agents](/docs/studio/agents.md).
- [Authentication and scopes](/docs/developers/auth.md), [MCP servers](/docs/developers/mcp.md) and [Errors, limits and pagination](/docs/developers/conventions.md).
