{"openapi":"3.1.0","info":{"title":"MDSlides API","version":"1.0.0","description":"Create and manage Markdown presentations. Authenticate with an API key from Settings → API and MCP. Errors return {\"error\": message, \"code\": stable_code}. Rate limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset."},"servers":[{"url":"https://mdslides.milab.es/api/v1"}],"externalDocs":{"url":"https://mdslides.milab.es/developers"},"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (mds_…). Scopes: read, write, ai."}},"schemas":{"CreatePresentation":{"type":"object","properties":{"title":{"description":"Optional; otherwise inferred from the first heading or generated.","type":"string","minLength":1,"maxLength":160},"md":{"description":"MDSlides Markdown. Send exactly one of md or topic.","type":"string","minLength":1,"maxLength":400000},"topic":{"description":"AI generation instructions (requires the ai scope and an OpenAI key in Settings).","type":"string","minLength":1,"maxLength":6000},"theme_id":{"description":"Theme ID from list_themes. Defaults to builtin:default.","type":"string","maxLength":100},"collection_id":{"description":"Optional collection (list) ID from list_collections.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"share":{"description":"true creates a public read-only link. Default false.","type":"boolean"},"count":{"description":"AI only: number of slides (default 8).","type":"integer","minimum":1,"maximum":40},"language":{"description":"AI only: slide language, e.g. English (default Spanish).","type":"string","minLength":1,"maxLength":100},"style":{"description":"AI only: tone and style.","type":"string","minLength":1,"maxLength":1000}},"additionalProperties":false},"UpdatePresentation":{"type":"object","properties":{"revision":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Current revision from get_presentation. A stale revision returns revision_conflict."},"title":{"type":"string","minLength":1,"maxLength":160},"md":{"description":"Replacement Markdown for the whole deck.","type":"string","minLength":1,"maxLength":400000},"theme_id":{"description":"New theme ID; its CSS is copied into the presentation.","type":"string","maxLength":100},"collection_id":{"description":"Collection ID, or null to remove it from its collection.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["revision"],"additionalProperties":false},"GenerateImage":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":8000,"pattern":"^[^\\r\\n]+$","description":"Single-line image description."},"ratio":{"description":"Defaults to the account image settings.","type":"string","enum":["1:1","16:9","9:16","3:2","2:3"]},"request_id":{"description":"Reuse the same UUID to retry safely without paying twice.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["prompt"],"additionalProperties":false},"Validate":{"type":"object","properties":{"md":{"type":"string","maxLength":400000}},"required":["md"],"additionalProperties":false},"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"detail":{"type":"string"},"required_scope":{"type":"string"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/me":{"get":{"summary":"Describe the current credential, its scopes and rate limit","description":"Any valid key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/format":{"get":{"summary":"Markdown format reference","description":"Any valid key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"section","in":"query","schema":{"type":"string","enum":["basics","text","slides","appearance","content","charts","themes"]}}]}},"/validate":{"post":{"summary":"Validate Markdown without saving","description":"Any valid key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validate"}}}}}},"/themes":{"get":{"summary":"List themes with mode, colours and fonts","description":"Requires the `read` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/collections":{"get":{"summary":"List collections","description":"Requires the `read` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/images":{"get":{"summary":"List library images","description":"Requires the `read` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"q","in":"query","required":false,"schema":{"description":"Filter by image description.","type":"string","maxLength":160},"description":"Filter by image description."},{"name":"presentation_id","in":"query","required":false,"schema":{"description":"Only images used in this presentation.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Only images used in this presentation."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000}}]}},"/presentations":{"get":{"summary":"List presentations","description":"Requires the `read` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"q","in":"query","required":false,"schema":{"description":"Case-insensitive title filter.","type":"string","maxLength":160},"description":"Case-insensitive title filter."},{"name":"collection_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"limit","in":"query","required":false,"schema":{"description":"Default 50.","type":"integer","minimum":1,"maximum":100},"description":"Default 50."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000}}]},"post":{"summary":"Create a presentation from Markdown or a topic","description":"topic additionally requires `ai`. Send an Idempotency-Key header to retry safely: a repeat within 24 hours returns the original response with Idempotent-Replayed: true. Requires the `write` scope.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePresentation"}}}}}},"/presentations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Read a presentation including its Markdown","description":"Requires the `read` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Update title, Markdown, theme or collection","description":"Send the current revision; a stale one returns 409 revision_conflict. Requires the `write` scope.","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePresentation"}}}}},"delete":{"summary":"Delete a presentation permanently","description":"Requires the `write` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/presentations/{id}/pdf":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Export the presentation as a PDF file","description":"Renders every visible slide as a 16:9 page (10 × 5.625 in) with selectable text, the deck theme and charts; speaker notes are left out. Rendering takes a few seconds. 422 no_visible_slides when nothing is visible. Requires the `read` scope.","responses":{"200":{"description":"The PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/presentations/{id}/pdf-link":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a signed PDF download link valid for one hour","description":"Returns download_url, expires_at, file_name and slide_count. Anyone with the link can download the PDF until it expires, without a key; the PDF is rendered when the link is opened. Requires the `read` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/presentations/{id}/share":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Enable the public link","description":"Requires the `write` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Revoke the public link","description":"Requires the `write` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/presentations/{id}/images":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Generate an image for a presentation","description":"Also requires `write`. Incurs charges on the account image provider. Requires the `ai` scope.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateImage"}}}}}}}}