{"openapi": "3.1.0", "info": {"title": "EaseWeb presentations API", "version": "1.0", "description": "Create, edit, read and review web presentations. The same operations are MCP tools at /mcp/. Guide for agents: /llms.txt"}, "servers": [{"url": "https://easeweb.host"}], "paths": {"/api/v1/me": {"get": {"operationId": "whoami", "summary": "Who am I", "description": "Who the API key belongs to and what it may do: the user name, the name of the key and its access\n(\"read\" or \"write\").", "tags": ["me"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/format": {"get": {"operationId": "get_format", "summary": "Block format reference", "description": "The complete reference of what a slide can contain: block types with every prop and its default,\nallowed values of every enumerated prop, number ranges, colour props, link kinds, fonts, shapes\nand themes.", "tags": ["format"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "security": []}}, "/api/v1/presentations": {"get": {"operationId": "list_presentations", "summary": "List presentations", "description": "Presentations: \"mine\" (default) -- yours; \"shared\" -- other people's that you were given access to;\n\"open\" -- open presentations of anybody, which every signed-in person or agent may read and edit.\nEach has slug, id, title, description, theme, access level, whether you can edit it, number of slides, address.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "scope", "in": "query", "required": false, "schema": {"type": "string", "enum": ["mine", "shared", "open"], "description": "Which presentations: \"mine\" (default), \"shared\" with you, or \"open\" ones of anybody."}, "description": "Which presentations: \"mine\" (default), \"shared\" with you, or \"open\" ones of anybody."}], "security": [{"bearer": []}, {"session": []}]}, "post": {"operationId": "create_presentation", "summary": "Create a presentation", "description": "Create a new presentation of yours, empty or complete in one call. \"slides\" is a list of\n{\"name\", \"w\", \"h\", \"bg\", \"fit\", \"background\", \"objects\": [blocks]}; blocks may link to each other's\nslides with {\"kind\": \"slide\", \"slide_number\": N} (1-based, in this list). Returns the new presentation\nwith the ids of its slides and blocks (every prop too with \"response\": \"full\").", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 100, "description": "Title (at most 100 characters)."}, "description": {"type": "string", "description": "Description shown on the presentation page (optional)."}, "theme": {"type": "string", "enum": ["light", "paper", "ocean", "coral", "dark", "forest"], "description": "Default colours of the slides and of new blocks."}, "slides": {"type": "array", "items": {"type": "object"}, "description": "Slides with their blocks (optional)."}, "database": {"type": "object", "additionalProperties": false, "description": "Setup scripts of the databases the runnable code blocks work in, by language. Every viewer runs the blocks in a private database made from the script (up to 50000 characters each; an empty string removes a script).", "properties": {"sql": {"type": "string", "description": "PostgreSQL SQL that creates and fills the database."}, "mongodb": {"type": "string", "description": "MongoDB shell (mongosh JavaScript) that creates and fills the database."}, "redis": {"type": "string", "description": "Redis commands that creates and fills the database."}}}, "response": {"type": "string", "enum": ["brief", "full"], "description": "\"brief\" (default): only the ids, numbers and types of the slides and blocks; \"full\": every prop of every block too."}}, "required": ["title"], "additionalProperties": false}}}}, "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}": {"get": {"operationId": "get_presentation", "summary": "Get a presentation for editing", "description": "A presentation you can see, with every slide and every block (ids and complete props), in playback\norder. Use the ids to edit slides and blocks (\"can_edit\" says whether you may). Links to slides show\nboth \"slide\" (id) and \"slide_number\".", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}, "patch": {"operationId": "update_presentation", "summary": "Change title, description, theme or database", "description": "Change the title, description or theme of a presentation you may edit, or (its author only) the setup scripts of\nthe databases its runnable code blocks work in. The theme only sets the defaults of new slides and blocks; existing\nslides keep their colours. The slug (address) does not change.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 100, "description": "New title (at most 100 characters)."}, "description": {"type": "string", "description": "New description; an empty string removes it."}, "theme": {"type": "string", "enum": ["light", "paper", "ocean", "coral", "dark", "forest"], "description": "Colour theme: the defaults of new slides and blocks."}, "database": {"type": "object", "additionalProperties": false, "description": "Setup scripts of the databases the runnable code blocks work in, by language. Every viewer runs the blocks in a private database made from the script (up to 50000 characters each; an empty string removes a script). Only the author may change them; the languages left out keep their scripts.", "properties": {"sql": {"type": "string", "description": "PostgreSQL SQL that creates and fills the database."}, "mongodb": {"type": "string", "description": "MongoDB shell (mongosh JavaScript) that creates and fills the database."}, "redis": {"type": "string", "description": "Redis commands that creates and fills the database."}}}}, "required": [], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}, "delete": {"operationId": "delete_presentation", "summary": "Delete a presentation", "description": "Delete one of your presentations (it disappears from the site and from the list of presentations).", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/read": {"get": {"operationId": "read_presentation", "summary": "Read any presentation", "description": "Read any presentation you can see (not private, or shared with you) the way a person sees it: slide by slide,\nthe texts in reading order, pictures' descriptions, code, and where every button or link leads.\nA card (a shape with a link and the blocks on it that lead to the same place) is one entry of type \"card\"\nwith the ids of all its blocks. format \"markdown\" (default) is compact; \"json\" is structured.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}, "text/markdown": {"schema": {"type": "string"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "format", "in": "query", "required": false, "schema": {"type": "string", "enum": ["markdown", "json"], "description": "Result format: \"markdown\" (default, compact) or \"json\" (structured)."}, "description": "Result format: \"markdown\" (default, compact) or \"json\" (structured)."}], "security": []}}, "/api/v1/presentations/{slug}/slides/{slide_id}": {"get": {"operationId": "get_slide", "summary": "Get one slide", "description": "One slide of a presentation you can see, with all of its blocks (ids and complete props).", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "slide_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}, "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}], "security": [{"bearer": []}, {"session": []}]}, "patch": {"operationId": "update_slide", "summary": "Change a slide", "description": "Change a slide: its name, size, background colour / picture, and -- when \"objects\" is given -- its\nCOMPLETE list of blocks: blocks with an existing \"id\" are kept (their props are merged with the given\nones), blocks without an id are added, blocks not in the list are deleted. Returns the slide (ids only unless \"response\" is \"full\").", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 100, "description": "Slide name (at most 100 characters)."}, "w": {"type": "integer", "description": "Canvas width in px (200-4000, default 1280)."}, "h": {"type": "integer", "description": "Canvas height in px (default 720)."}, "bg": {"type": "string", "description": "Background colour, #rrggbb."}, "fit": {"type": "string", "enum": ["contain", "cover", "stretch"], "description": "How the background picture fits."}, "background": {"type": ["string", "null"], "description": "Background picture: the \"src\" of an uploaded picture; null removes it."}, "objects": {"type": "array", "description": "Blocks of the slide, bottom to top: [{\"type\": \"text\"|\"shape\"|\"button\"|\"line\"|\"image\"|\"code\", \"props\": {...}}]. Missing props take the presentation theme's defaults (every prop is described in the block format reference). A link to a slide of the same presentation may be given as {\"kind\": \"slide\", \"slide_number\": N}.", "items": {"type": "object"}}, "response": {"type": "string", "enum": ["brief", "full"], "description": "\"brief\" (default): only the ids, numbers and types of the slides and blocks; \"full\": every prop of every block too."}}, "required": [], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "slide_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}, "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}], "security": [{"bearer": []}, {"session": []}]}, "delete": {"operationId": "delete_slide", "summary": "Delete a slide", "description": "Delete a slide of your presentation. Links that led to it stop leading anywhere.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "slide_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}, "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/slides": {"post": {"operationId": "add_slide", "summary": "Add a slide", "description": "Add a slide to a presentation you may edit, at the end or at \"position\" (1-based), optionally with its blocks\nright away. Returns the new slide (ids only unless \"response\" is \"full\").", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"position": {"type": "integer", "description": "1-based place; default: the end."}, "name": {"type": "string", "maxLength": 100, "description": "Slide name (at most 100 characters)."}, "w": {"type": "integer", "description": "Canvas width in px (200-4000, default 1280)."}, "h": {"type": "integer", "description": "Canvas height in px (default 720)."}, "bg": {"type": "string", "description": "Background colour, #rrggbb."}, "fit": {"type": "string", "enum": ["contain", "cover", "stretch"], "description": "How the background picture fits."}, "background": {"type": ["string", "null"], "description": "Background picture: the \"src\" of an uploaded picture; null removes it."}, "objects": {"type": "array", "description": "Blocks of the slide, bottom to top: [{\"type\": \"text\"|\"shape\"|\"button\"|\"line\"|\"image\"|\"code\", \"props\": {...}}]. Missing props take the presentation theme's defaults (every prop is described in the block format reference). A link to a slide of the same presentation may be given as {\"kind\": \"slide\", \"slide_number\": N}.", "items": {"type": "object"}}, "response": {"type": "string", "enum": ["brief", "full"], "description": "\"brief\" (default): only the ids, numbers and types of the slides and blocks; \"full\": every prop of every block too."}}, "required": [], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/slides/batch": {"post": {"operationId": "add_slides", "summary": "Add several slides", "description": "Add several slides at once to a presentation you may edit, at the end or from \"position\" (1-based) on. Each slide is\n{\"name\", \"w\", \"h\", \"bg\", \"fit\", \"background\", \"objects\": [blocks]}. A link {\"kind\": \"slide\", \"slide_number\": N} counts\nthe slides of the presentation as they are after the insertion, so new slides may lead to each other.\nReturns the new slides (ids only unless \"response\" is \"full\").", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"position": {"type": "integer", "description": "1-based place of the first new slide; default: the end."}, "slides": {"type": "array", "items": {"type": "object"}, "minItems": 1, "description": "The slides: [{\"name\", \"w\", \"h\", \"bg\", \"fit\", \"background\", \"objects\"}]."}, "response": {"type": "string", "enum": ["brief", "full"], "description": "\"brief\" (default): only the ids, numbers and types of the slides and blocks; \"full\": every prop of every block too."}}, "required": ["slides"], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/slides/{slide_id}/blocks": {"post": {"operationId": "edit_blocks", "summary": "Add, change or delete blocks", "description": "Change some blocks of a slide and leave the others alone, in one step:\n\"add\": new blocks [{\"type\", \"props\"}] (placed on top, or at the bottom with \"at_bottom\": true);\n\"update\": [{\"id\", \"props\"}] -- only the given props change. The same props for several blocks at once, like\nselecting them in the editor: {\"ids\": [...], \"props\"}; or for a card and everything drawn on it:\n{\"inside\": <id of the card's background block>, \"props\"} -- that block and every block lying within its\nrectangle (props a block type does not have, like \"link\" of a code block, are skipped for it);\n\"delete\": [block ids]. Returns the slide (ids only unless \"response\" is \"full\").", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"add": {"type": "array", "items": {"type": "object"}, "description": "New blocks: [{\"type\", \"props\"}]."}, "update": {"type": "array", "items": {"type": "object"}, "description": "Changes: [{\"id\" | \"ids\": [...] | \"inside\": <card block id>, \"props\"}]."}, "delete": {"type": "array", "items": {"type": "integer"}, "description": "Ids of blocks to delete."}, "at_bottom": {"type": "boolean", "description": "Put the added blocks under the others (default: on top)."}, "response": {"type": "string", "enum": ["brief", "full"], "description": "\"brief\" (default): only the ids, numbers and types of the slides and blocks; \"full\": every prop of every block too."}}, "required": [], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "slide_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}, "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/slides/order": {"put": {"operationId": "reorder_slides", "summary": "Reorder slides", "description": "Set the playback order: \"order\" lists the ids of ALL slides of the presentation in the new order.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"order": {"type": "array", "items": {"type": "integer"}, "description": "Every slide id, once."}}, "required": ["order"], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/images": {"post": {"operationId": "upload_image", "summary": "Upload a picture", "description": "Store a picture (PNG, JPEG, GIF or WEBP, up to 25 MB, base64-encoded) and get its \"src\" for an image\nblock or a slide background. Big pictures are scaled down to 2560 px.", "tags": ["images"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"data_base64": {"type": "string", "description": "The file, base64 (a data: URL prefix is allowed)."}}, "required": ["data_base64"], "additionalProperties": false}}}}, "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/import": {"post": {"operationId": "import_presentation", "summary": "Import a PowerPoint or EaseWeb file", "description": "Create a new presentation of yours from a PowerPoint file (.pptx) or an EaseWeb archive (.zip, as exported by the\nsite): slides, texts with their formatting, shapes, pictures, backgrounds and links become editable blocks, the way\nthe \"Import\" button of the site does it. Returns the new presentation (ids only unless \"response\" is \"full\") and\n\"warnings\" about what could not be converted.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"data_base64": {"type": "string", "description": "The file, base64 (a data: URL prefix is allowed; at most 28 MB)."}, "filename": {"type": "string", "description": "Name of the file, like \"lecture.pptx\" (its extension helps to recognise the format; without a title, it gives the title)."}, "title": {"type": "string", "maxLength": 100, "description": "Title of the new presentation (optional)."}, "response": {"type": "string", "enum": ["brief", "full"], "description": "\"brief\" (default): only the ids, numbers and types of the slides and blocks; \"full\": every prop of every block too."}}, "required": ["data_base64"], "additionalProperties": false}}}}, "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/run": {"post": {"operationId": "run_code", "summary": "Run code", "description": "Run code the way the Run button of a code block does, to check it: \"sql\", \"mongodb\" and \"redis\" run in your own\ndatabase of the presentation (made from its database scripts; what you change stays in it), \"python\" and \"bash\"\nin a sandbox without network that keeps nothing. The presentation itself does not change.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"lang": {"type": "string", "enum": ["sql", "mongodb", "redis", "python", "bash"], "description": "Language of the code."}, "code": {"type": "string", "description": "The code (at most 20000 characters)."}, "reset": {"type": "boolean", "description": "sql, mongodb, redis: first make your database again from the script of the presentation."}}, "required": ["lang", "code"], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/comments": {"get": {"operationId": "list_comments", "summary": "Read the notes", "description": "Notes on a presentation, as threads with replies. The owner sees every note; anybody else sees the\nthreads they started (and the replies to them). Without \"include_resolved\" only open threads.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "slide_id", "in": "query", "required": false, "schema": {"type": "integer", "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}, "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}, {"name": "include_resolved", "in": "query", "required": false, "schema": {"type": "boolean", "description": "Also return resolved threads (default: only open ones)."}, "description": "Also return resolved threads (default: only open ones)."}], "security": [{"bearer": []}, {"session": []}]}, "post": {"operationId": "add_comment", "summary": "Leave a note", "description": "Leave a note on any presentation you can see -- on a slide (\"slide_id\") or on the whole presentation --\nor answer a thread (\"reply_to\"). The owner of the presentation sees the note in the viewer; the thread is\nseen by the owner and by whoever started it.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"text": {"type": "string", "maxLength": 4000, "description": "The note (plain text, up to 4000 characters)."}, "slide_id": {"type": "integer", "description": "The id of a slide (stable, the \"id\" of the slide in the presentation). Its number (position) changes when slides are reordered."}, "reply_to": {"type": "integer", "description": "The id of a note to answer."}}, "required": ["text"], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/comments/{comment_id}/resolve": {"post": {"operationId": "resolve_comment", "summary": "Resolve a note", "description": "Mark a thread as done (or open it again with \"resolved\": false). The owner of the presentation or the\none who started the thread may do it.", "tags": ["comments"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"resolved": {"type": "boolean", "description": "Default true."}}, "required": [], "additionalProperties": false}}}}, "parameters": [{"name": "comment_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "The id of a note."}, "description": "The id of a note."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/comments/{comment_id}": {"delete": {"operationId": "delete_comment", "summary": "Delete a note", "description": "Delete a note (with its replies, when it starts a thread). Its author or the owner of the presentation may do it.", "tags": ["comments"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "comment_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "The id of a note."}, "description": "The id of a note."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/access-requests": {"post": {"operationId": "request_access", "summary": "Ask for access", "description": "Ask the author of a presentation for access: \"view\" to read a private one, \"edit\" to change one that is\nnot open. The author sees the request on the site and approves or declines it; then the access belongs\nto your account (you and all of your agents). Asking again updates the pending request.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"role": {"type": "string", "enum": ["view", "edit"], "description": "\"view\" -- read; \"edit\" -- read and change."}, "message": {"type": "string", "description": "Why you need it (optional)."}}, "required": [], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/access-requests": {"get": {"operationId": "list_access_requests", "summary": "Access requests", "description": "\"incoming\" (default): requests for access to YOUR presentations (pending ones, or all with\ninclude_decided); \"outgoing\": the requests you (or your agents) sent and their status.", "tags": ["access-requests"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "direction", "in": "query", "required": false, "schema": {"type": "string", "enum": ["incoming", "outgoing"], "description": "\"incoming\" (default): requests to you; \"outgoing\": requests you sent."}, "description": "\"incoming\" (default): requests to you; \"outgoing\": requests you sent."}, {"name": "include_decided", "in": "query", "required": false, "schema": {"type": "boolean", "description": "Also return approved and declined requests."}, "description": "Also return approved and declined requests."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/access-requests/{request_id}": {"post": {"operationId": "answer_access_request", "summary": "Answer an access request", "description": "Approve or decline a request for access to one of your presentations. \"role\" may change what is given\n(default: what was asked for).", "tags": ["access-requests"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"approve": {"type": "boolean", "description": "true approves the request, false declines it."}, "role": {"type": "string", "enum": ["view", "edit"], "description": "\"view\" -- read; \"edit\" -- read and change."}}, "required": ["approve"], "additionalProperties": false}}}}, "parameters": [{"name": "request_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "The id of the access request."}, "description": "The id of the access request."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/access": {"get": {"operationId": "get_access", "summary": "Access settings", "description": "The access settings of your presentation: its level (\"open\", \"public\", \"private\"), who was given access\n(and which role), and the pending requests.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}, "patch": {"operationId": "set_access", "summary": "Change access", "description": "Change the access of your presentation: \"level\" -- \"open\" (every signed-in person and agent reads and\nedits; the history keeps every change), \"public\" (everybody reads, those given access edit) or\n\"private\" (only those given access); \"revoke\" -- usernames whose access is taken away.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"level": {"type": "string", "enum": ["open", "public", "private"], "description": "New access level: \"open\", \"public\" or \"private\"."}, "revoke": {"type": "array", "items": {"type": "string"}, "description": "User names whose access is taken away."}}, "required": [], "additionalProperties": false}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/history": {"get": {"operationId": "list_history", "summary": "History of changes", "description": "The versions of a presentation you can see, newest first: number, who made it (person and agent),\nwhen, and what changed. Changes of one author in a row within 10 minutes are one version.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "description": "At most this many (default 50)."}, "description": "At most this many (default 50)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/history/{number}": {"get": {"operationId": "get_version", "summary": "Content of a version", "description": "What a presentation looked like in a version: \"markdown\" (default) -- its slides and texts as\nmarkdown; \"json\" -- the complete content.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "number", "in": "path", "required": true, "schema": {"type": "integer", "description": "The version number."}, "description": "The version number."}, {"name": "format", "in": "query", "required": false, "schema": {"type": "string", "enum": ["markdown", "json"], "description": "Result format: \"markdown\" (default) or \"json\" (the complete content)."}, "description": "Result format: \"markdown\" (default) or \"json\" (the complete content)."}], "security": [{"bearer": []}, {"session": []}]}}, "/api/v1/presentations/{slug}/history/{number}/restore": {"post": {"operationId": "restore_version", "summary": "Go back to a version", "description": "Make a presentation you may edit look exactly as it did in a version (slides, blocks, order, title).\nThe restore is a new version itself, so it can be undone the same way.", "tags": ["presentations"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "4XX": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "description": "The presentation's slug (its address: /movie/<slug>/)."}, "description": "The presentation's slug (its address: /movie/<slug>/)."}, {"name": "number", "in": "path", "required": true, "schema": {"type": "integer", "description": "The version number."}, "description": "The version number."}], "security": [{"bearer": []}, {"session": []}]}}}, "components": {"securitySchemes": {"bearer": {"type": "http", "scheme": "bearer", "description": "An API key from /agents/"}, "session": {"type": "apiKey", "in": "cookie", "name": "sessionid"}}, "schemas": {"Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "path": {"type": "string"}}}}}}}}