{"openapi":"3.1.0","info":{"title":"PlantUML API Server","description":"**Diagrams as Code — UML, Cloud Architecture, Kubernetes, C4 and more.**\n\nA modern REST API and developer portal around the official **PlantUML Server**. It does\nnot reinvent PlantUML — it exposes it elegantly: render diagrams to PNG/SVG/TXT/PDF,\nencode/decode PlantUML URLs, and discover the architecture icon libraries (AWS, Azure,\nKubernetes, C4, GCP, OSA, Material and more), themes and curated examples.\n\nYou can always submit **plain PlantUML source** — the `theme` and `libraries` options are\nconveniences, never a replacement for PlantUML syntax.\n\n* Interactive **editor**: [`/editor`](/editor)\n* This documentation: [`/docs`](/docs) · OpenAPI schema: [`/openapi.json`](/openapi.json)\n* Health: [`/health`](/health) · Prometheus metrics: [`/metrics`](/metrics)","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"version":"1.0.0"},"paths":{"/health":{"get":{"tags":["System"],"summary":"Health check","description":"Reports overall service health plus the PlantUML backend status and version. Always returns HTTP 200 so simple probes can read the JSON body.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1":{"get":{"tags":["System"],"summary":"API discovery","description":"Service metadata and links to the API's main entry points.","operationId":"api_info_api_v1_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInfo"}}}}}}},"/api/v1/render":{"post":{"tags":["Rendering"],"summary":"Render a PlantUML diagram","description":"Render PlantUML source to the requested format (PNG, SVG, TXT, PDF, …). Returns the native media type — binary responses are streamed, not base64-encoded. Submit normal PlantUML source; `theme` and `libraries` are optional conveniences.","operationId":"render_api_v1_render_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"}}},"required":true},"responses":{"200":{"description":"The rendered diagram in the requested media type.","content":{"application/json":{"schema":{}},"image/png":{},"image/svg+xml":{},"text/plain":{},"application/pdf":{}}},"422":{"description":"Invalid PlantUML source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"PlantUML backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"PlantUML render timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/encode":{"post":{"tags":["Encoding"],"summary":"Encode PlantUML source","description":"Encode PlantUML source into the URL-safe token used by the PlantUML Server, and return ready-to-use editor / PNG / SVG / TXT URLs.","operationId":"encode_api_v1_encode_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EncodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EncodeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/decode":{"post":{"tags":["Encoding"],"summary":"Decode a PlantUML token","description":"Decode a PlantUML URL token (deflate, `~1` or `~h` hex forms) back into diagram source.","operationId":"decode_api_v1_decode_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeResponse"}}}},"422":{"description":"Malformed token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/libraries":{"get":{"tags":["Libraries"],"summary":"List architecture / icon libraries","description":"Discover the PlantUML standard-library icon and architecture libraries supported by this service (AWS, Azure, Kubernetes, C4, OSA, Material, GCP, …).","operationId":"list_libraries_api_v1_libraries_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Library"},"type":"array","title":"Response List Libraries Api V1 Libraries Get"}}}}}}},"/api/v1/libraries/{library}":{"get":{"tags":["Libraries"],"summary":"Get a single library","operationId":"get_library_api_v1_libraries__library__get","parameters":[{"name":"library","in":"path","required":true,"schema":{"type":"string","title":"Library"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Library"}}}},"404":{"description":"Unknown library."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/libraries/{library}/examples":{"get":{"tags":["Libraries"],"summary":"Examples that use a library","operationId":"library_examples_api_v1_libraries__library__examples_get","parameters":[{"name":"library","in":"path","required":true,"schema":{"type":"string","title":"Library"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Example"},"title":"Response Library Examples Api V1 Libraries  Library  Examples Get"}}}},"404":{"description":"Unknown library."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/libraries/{library}/icons":{"get":{"tags":["Libraries"],"summary":"Discover a library's icon categories","description":"Returns the icon categories exposed by a library. Full per-icon sprite enumeration is best explored in the editor's autocomplete; the categories here give the top-level groupings.","operationId":"library_icons_api_v1_libraries__library__icons_get","parameters":[{"name":"library","in":"path","required":true,"schema":{"type":"string","title":"Library"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Library Icons Api V1 Libraries  Library  Icons Get"}}}},"404":{"description":"Unknown library."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/themes":{"get":{"tags":["Themes"],"summary":"List PlantUML themes","description":"Discover the PlantUML themes supported by this service. Apply one with `!theme <name>` in your source, or via the `theme` field of /api/v1/render.","operationId":"list_themes_api_v1_themes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Theme"},"type":"array","title":"Response List Themes Api V1 Themes Get"}}}}}}},"/api/v1/themes/{theme_id}":{"get":{"tags":["Themes"],"summary":"Get a single theme","operationId":"get_theme_api_v1_themes__theme_id__get","parameters":[{"name":"theme_id","in":"path","required":true,"schema":{"type":"string","title":"Theme Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Theme"}}}},"404":{"description":"Unknown theme."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/examples":{"get":{"tags":["Examples"],"summary":"List curated examples","description":"A curated gallery covering UML, AWS, Azure, Kubernetes, C4, GCP, network/security, icon libraries, themes and PlantUML's non-UML diagram types.","operationId":"list_examples_api_v1_examples_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ExampleSummary"},"type":"array","title":"Response List Examples Api V1 Examples Get"}}}}}}},"/api/v1/examples/{example_id}":{"get":{"tags":["Examples"],"summary":"Get one example with render URLs","operationId":"get_example_api_v1_examples__example_id__get","parameters":[{"name":"example_id","in":"path","required":true,"schema":{"type":"string","title":"Example Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExampleDetail"}}}},"404":{"description":"Unknown example."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ApiInfo":{"properties":{"service":{"type":"string","title":"Service"},"api_version":{"type":"string","title":"Api Version"},"plantuml_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plantuml Version"},"openapi":{"type":"string","title":"Openapi"},"docs":{"type":"string","title":"Docs"},"editor":{"type":"string","title":"Editor"},"health":{"type":"string","title":"Health"},"metrics":{"type":"string","title":"Metrics"},"libraries":{"type":"string","title":"Libraries"},"themes":{"type":"string","title":"Themes"},"examples":{"type":"string","title":"Examples"}},"type":"object","required":["service","api_version","plantuml_version","openapi","docs","editor","health","metrics","libraries","themes","examples"],"title":"ApiInfo"},"BackendHealth":{"properties":{"status":{"type":"string","title":"Status","description":"`healthy` | `unhealthy`."},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Running PlantUML version."}},"type":"object","required":["status"],"title":"BackendHealth"},"DecodeRequest":{"properties":{"encoded":{"type":"string","minLength":1,"title":"Encoded","description":"PlantUML encoded token to decode."}},"type":"object","required":["encoded"],"title":"DecodeRequest","examples":[{"encoded":"SyfFKj2rKt3CoKnELR1Io4ZDoSa70000"}]},"DecodeResponse":{"properties":{"source":{"type":"string","title":"Source"}},"type":"object","required":["source"],"title":"DecodeResponse"},"EncodeRequest":{"properties":{"source":{"type":"string","minLength":1,"title":"Source","description":"PlantUML source to encode."}},"type":"object","required":["source"],"title":"EncodeRequest","examples":[{"source":"@startuml\nAlice -> Bob\n@enduml"}]},"EncodeResponse":{"properties":{"encoded":{"type":"string","title":"Encoded","description":"PlantUML URL-safe encoded token."},"editor_url":{"type":"string","title":"Editor Url"},"png_url":{"type":"string","title":"Png Url"},"svg_url":{"type":"string","title":"Svg Url"},"txt_url":{"type":"string","title":"Txt Url"}},"type":"object","required":["encoded","editor_url","png_url","svg_url","txt_url"],"title":"EncodeResponse"},"ErrorResponse":{"properties":{"type":{"type":"string","title":"Type","default":"about:blank"},"title":{"type":"string","title":"Title"},"status":{"type":"integer","title":"Status"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"type":"object","required":["title","status"],"title":"ErrorResponse","description":"RFC 7807-style problem detail."},"Example":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"category":{"type":"string","title":"Category"},"libraries":{"items":{"type":"string"},"type":"array","title":"Libraries"},"source":{"type":"string","title":"Source"}},"type":"object","required":["id","title","description","category","source"],"title":"Example"},"ExampleDetail":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"category":{"type":"string","title":"Category"},"libraries":{"items":{"type":"string"},"type":"array","title":"Libraries"},"source":{"type":"string","title":"Source"},"encoded":{"type":"string","title":"Encoded"},"svg_url":{"type":"string","title":"Svg Url"},"png_url":{"type":"string","title":"Png Url"},"editor_url":{"type":"string","title":"Editor Url"},"api_request":{"additionalProperties":true,"type":"object","title":"Api Request"}},"type":"object","required":["id","title","description","category","source","encoded","svg_url","png_url","editor_url","api_request"],"title":"ExampleDetail","description":"An example plus ready-to-use render/editor URLs and a sample API request."},"ExampleSummary":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"category":{"type":"string","title":"Category"},"libraries":{"items":{"type":"string"},"type":"array","title":"Libraries"}},"type":"object","required":["id","title","description","category"],"title":"ExampleSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Overall service status: `healthy` | `degraded`."},"api_version":{"type":"string","title":"Api Version"},"plantuml":{"$ref":"#/components/schemas/BackendHealth"}},"type":"object","required":["status","api_version","plantuml"],"title":"HealthResponse"},"Library":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"builtin":{"type":"boolean","title":"Builtin","description":"Whether the library ships with PlantUML stdlib."},"description":{"type":"string","title":"Description"},"include":{"type":"string","title":"Include","description":"The `!include` line(s) that load the library."},"docs_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Docs Url"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"}},"type":"object","required":["id","name","builtin","description","include"],"title":"Library"},"RenderFormat":{"type":"string","enum":["png","svg","txt","utxt","pdf","eps"],"title":"RenderFormat","description":"Output formats the API exposes (a subset the PlantUML Server supports)."},"RenderRequest":{"properties":{"source":{"type":"string","minLength":1,"title":"Source","description":"PlantUML source. Submit normal PlantUML — `@startuml … @enduml`."},"format":{"$ref":"#/components/schemas/RenderFormat","description":"Desired output format.","default":"svg"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Theme","description":"Optional PlantUML theme name, injected as `!theme <name>`."},"libraries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Libraries","description":"Optional known library ids (see /api/v1/libraries) whose `!include` lines are injected for convenience. You can always include them yourself instead."},"index":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Index","description":"Diagram index for a source containing multiple `@startuml` blocks."}},"type":"object","required":["source"],"title":"RenderRequest","examples":[{"format":"svg","source":"@startuml\nAlice -> Bob: Hello\nBob --> Alice: Hi!\n@enduml"},{"format":"png","libraries":["awslib"],"source":"@startuml\nComponent [Web] as web\n@enduml","theme":"cerulean"}]},"Theme":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"preview_source":{"type":"string","title":"Preview Source","description":"A tiny PlantUML source that demonstrates the theme."}},"type":"object","required":["id","name","preview_source"],"title":"Theme"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Rendering","description":"Render PlantUML source to images and text."},{"name":"Encoding","description":"Encode/decode PlantUML URL tokens."},{"name":"Libraries","description":"Discover architecture & icon libraries."},{"name":"Themes","description":"Discover PlantUML themes."},{"name":"Examples","description":"Curated, ready-to-render example gallery."},{"name":"System","description":"Health, metrics and API discovery."}]}