# EaseWeb

> Web presentations: slides with text, shapes, buttons, lines, pictures and code, played in the browser. People and AI agents create, edit, read and review them.

## Connect

- MCP server (Streamable HTTP): https://easeweb.host/mcp/ -- sign in with OAuth 2.1 (discovery: https://easeweb.host/.well-known/oauth-protected-resource/mcp; client ID metadata documents or dynamic client registration, PKCE; server card: /.well-known/mcp/server-card.json), or send the header `Authorization: Bearer <key>`
- REST API: https://easeweb.host/api/v1/... with the same header; OpenAPI: https://easeweb.host/api/v1/openapi.json
- A person signs in at https://easeweb.host and creates a key for an agent at https://easeweb.host/agents/ (read-only or read-write).
- For people: how to connect Claude, ChatGPT, Cursor and other apps: https://easeweb.host/docs/mcp/ ; privacy policy: https://easeweb.host/privacy/ ; terms of service: https://easeweb.host/terms/
- Without a key: read any presentation as markdown: GET https://easeweb.host/api/v1/presentations/<slug>/read (the slug is in the address /movie/<slug>/...), and the block format: GET https://easeweb.host/api/v1/format

## How to work

1. get_format once: every block prop, its default and allowed values.
2. list_presentations / get_presentation to see yours (ids of slides and blocks).
3. create_presentation builds a whole presentation in one call; import_presentation turns a .pptx (or an EaseWeb .zip)
   into one; add_slides / add_slide / update_slide / edit_blocks change it. These answer with ids only; pass
   "response": "full" to get every prop back.
   Coordinates are px on the slide canvas (1280x720 by default). Missing props take the theme's defaults.
   Link a button to another slide with {"kind": "slide", "slide_number": N}.
4. Pictures: upload_image (base64) -> use its "src".
   Code blocks: "code" + "lang"; "runnable": true gives viewers a Run button (sql, mongodb, redis, python, bash).
   The databases of sql / mongodb / redis blocks are made from the presentation's "database" scripts
   (create_presentation / update_presentation); run_code checks a snippet the way the Run button does.
5. read_presentation reads ANY published presentation as markdown -- also to check your own result.
6. Notes: add_comment to review a presentation or to answer; list_comments to read what others wrote; resolve_comment when done.
7. Access: an "open" presentation (list_presentations scope "open") may be read and edited by anyone; "public" is read by
   everyone, edited by its author and those given access; "private" is seen only with access. Without access, call
   request_access (role "view" or "edit") -- the author approves it on the site; then retry.
8. History: every change is a version (list_history, get_version); restore_version goes back and can itself be undone.
   Before a big change of somebody else's presentation, leave a note (add_comment) saying what and why.
Every presentation has an address (url) people can open in a browser.

## Operations (MCP tool name = REST operationId)

- `whoami` -- GET /api/v1/me (any key). Who the API key belongs to and what it may do: the user name, the name of the key and its access ("read" or "write").
- `get_format` -- GET /api/v1/format (no key needed). The complete reference of what a slide can contain: block types with every prop and its default, allowed values of every enumerated prop, number ranges, colour props, link kinds, fonts, shapes and themes.
- `list_presentations` -- GET /api/v1/presentations (any key). Presentations: "mine" (default) -- yours; "shared" -- other people's that you were given access to; "open" -- open presentations of anybody, which every signed-in person or agent may read and edit. Each has slug, id, title, description, theme, access level, whether you can edit it, number of slides, address.
- `get_presentation` -- GET /api/v1/presentations/{slug} (any key). A presentation you can see, with every slide and every block (ids and complete props), in playback order. Use the ids to edit slides and blocks ("can_edit" says whether you may). Links to slides show both "slide" (id) and "slide_number".
- `read_presentation` -- GET /api/v1/presentations/{slug}/read (no key needed). Read any presentation you can see (not private, or shared with you) the way a person sees it: slide by slide, the texts in reading order, pictures' descriptions, code, and where every button or link leads. A card (a shape with a link and the blocks on it that lead to the same place) is one entry of type "card" with the ids of all its blocks. format "markdown" (default) is compact; "json" is structured.
- `create_presentation` -- POST /api/v1/presentations (read-write key). Create a new presentation of yours, empty or complete in one call. "slides" is a list of {"name", "w", "h", "bg", "fit", "background", "objects": [blocks]}; blocks may link to each other's slides with {"kind": "slide", "slide_number": N} (1-based, in this list). Returns the new presentation with the ids of its slides and blocks (every prop too with "response": "full").
- `update_presentation` -- PATCH /api/v1/presentations/{slug} (read-write key). Change the title, description or theme of a presentation you may edit, or (its author only) the setup scripts of the databases its runnable code blocks work in. The theme only sets the defaults of new slides and blocks; existing slides keep their colours. The slug (address) does not change.
- `delete_presentation` -- DELETE /api/v1/presentations/{slug} (read-write key). Delete one of your presentations (it disappears from the site and from the list of presentations).
- `get_slide` -- GET /api/v1/presentations/{slug}/slides/{slide_id} (any key). One slide of a presentation you can see, with all of its blocks (ids and complete props).
- `add_slide` -- POST /api/v1/presentations/{slug}/slides (read-write key). Add a slide to a presentation you may edit, at the end or at "position" (1-based), optionally with its blocks right away. Returns the new slide (ids only unless "response" is "full").
- `add_slides` -- POST /api/v1/presentations/{slug}/slides/batch (read-write key). Add several slides at once to a presentation you may edit, at the end or from "position" (1-based) on. Each slide is {"name", "w", "h", "bg", "fit", "background", "objects": [blocks]}. A link {"kind": "slide", "slide_number": N} counts the slides of the presentation as they are after the insertion, so new slides may lead to each other. Returns the new slides (ids only unless "response" is "full").
- `update_slide` -- PATCH /api/v1/presentations/{slug}/slides/{slide_id} (read-write key). Change a slide: its name, size, background colour / picture, and -- when "objects" is given -- its COMPLETE list of blocks: blocks with an existing "id" are kept (their props are merged with the given ones), blocks without an id are added, blocks not in the list are deleted. Returns the slide (ids only unless "response" is "full").
- `edit_blocks` -- POST /api/v1/presentations/{slug}/slides/{slide_id}/blocks (read-write key). Change some blocks of a slide and leave the others alone, in one step: "add": new blocks [{"type", "props"}] (placed on top, or at the bottom with "at_bottom": true); "update": [{"id", "props"}] -- only the given props change. The same props for several blocks at once, like selecting them in the editor: {"ids": [...], "props"}; or for a card and everything drawn on it: {"inside": <id of the card's background block>, "props"} -- that block and every block lying within its rectangle (props a block type does not have, like "link" of a code block, are skipped for it); "delete": [block ids]. Returns the slide (ids only unless "response" is "full").
- `delete_slide` -- DELETE /api/v1/presentations/{slug}/slides/{slide_id} (read-write key). Delete a slide of your presentation. Links that led to it stop leading anywhere.
- `reorder_slides` -- PUT /api/v1/presentations/{slug}/slides/order (read-write key). Set the playback order: "order" lists the ids of ALL slides of the presentation in the new order.
- `upload_image` -- POST /api/v1/images (read-write key). Store a picture (PNG, JPEG, GIF or WEBP, up to 25 MB, base64-encoded) and get its "src" for an image block or a slide background. Big pictures are scaled down to 2560 px.
- `import_presentation` -- POST /api/v1/presentations/import (read-write key). Create a new presentation of yours from a PowerPoint file (.pptx) or an EaseWeb archive (.zip, as exported by the site): slides, texts with their formatting, shapes, pictures, backgrounds and links become editable blocks, the way the "Import" button of the site does it. Returns the new presentation (ids only unless "response" is "full") and "warnings" about what could not be converted.
- `run_code` -- POST /api/v1/presentations/{slug}/run (any key). Run code the way the Run button of a code block does, to check it: "sql", "mongodb" and "redis" run in your own database of the presentation (made from its database scripts; what you change stays in it), "python" and "bash" in a sandbox without network that keeps nothing. The presentation itself does not change.
- `list_comments` -- GET /api/v1/presentations/{slug}/comments (any key). Notes on a presentation, as threads with replies. The owner sees every note; anybody else sees the threads they started (and the replies to them). Without "include_resolved" only open threads.
- `add_comment` -- POST /api/v1/presentations/{slug}/comments (read-write key). Leave a note on any presentation you can see -- on a slide ("slide_id") or on the whole presentation -- or answer a thread ("reply_to"). The owner of the presentation sees the note in the viewer; the thread is seen by the owner and by whoever started it.
- `resolve_comment` -- POST /api/v1/comments/{comment_id}/resolve (read-write key). Mark a thread as done (or open it again with "resolved": false). The owner of the presentation or the one who started the thread may do it.
- `delete_comment` -- DELETE /api/v1/comments/{comment_id} (read-write key). Delete a note (with its replies, when it starts a thread). Its author or the owner of the presentation may do it.
- `request_access` -- POST /api/v1/presentations/{slug}/access-requests (any key). Ask the author of a presentation for access: "view" to read a private one, "edit" to change one that is not open. The author sees the request on the site and approves or declines it; then the access belongs to your account (you and all of your agents). Asking again updates the pending request.
- `list_access_requests` -- GET /api/v1/access-requests (any key). "incoming" (default): requests for access to YOUR presentations (pending ones, or all with include_decided); "outgoing": the requests you (or your agents) sent and their status.
- `answer_access_request` -- POST /api/v1/access-requests/{request_id} (read-write key). Approve or decline a request for access to one of your presentations. "role" may change what is given (default: what was asked for).
- `get_access` -- GET /api/v1/presentations/{slug}/access (any key). The access settings of your presentation: its level ("open", "public", "private"), who was given access (and which role), and the pending requests.
- `set_access` -- PATCH /api/v1/presentations/{slug}/access (read-write key). Change the access of your presentation: "level" -- "open" (every signed-in person and agent reads and edits; the history keeps every change), "public" (everybody reads, those given access edit) or "private" (only those given access); "revoke" -- usernames whose access is taken away.
- `list_history` -- GET /api/v1/presentations/{slug}/history (any key). The versions of a presentation you can see, newest first: number, who made it (person and agent), when, and what changed. Changes of one author in a row within 10 minutes are one version.
- `get_version` -- GET /api/v1/presentations/{slug}/history/{number} (any key). What a presentation looked like in a version: "markdown" (default) -- its slides and texts as markdown; "json" -- the complete content.
- `restore_version` -- POST /api/v1/presentations/{slug}/history/{number}/restore (read-write key). Make a presentation you may edit look exactly as it did in a version (slides, blocks, order, title). The restore is a new version itself, so it can be undone the same way.

## Notes

- Errors: HTTP 4xx with {"error": {"code", "message", "path"}}; in MCP a tool result with isError=true.
- Slides have stable ids; their numbers (1-based positions) change when slides are reordered.
- A block is {"id", "type", "props"}. Coordinates are px from the top-left corner of the slide canvas.
- Text is a small HTML subset (b, i, u, s, sub, sup, p, div, ul, ol, li, br, span with color).
- Notes (comments) are seen by the owner of the presentation and by the one who started the thread.
- Access levels: open (anyone signed in reads and edits), public (everyone reads; the author and those given access edit), private (only with access). No access: 403 with code no_access / no_edit_access -> request_access.
- Every change is a version with its author and agent: list_history, get_version, restore_version.