Documentation

Quick Start

Embed a diagram in any webpage, wiki, or README with a single <img> tag. No signup required.

<img src="https://app.yuml.me/diagram/v1/class/clean/[Customer]->[Order].svg">

That's it. The URL is the diagram. Change the text, and the image updates.

Coming from v1?

If you've been embedding diagrams from yuml.me's original API (the one that's been running since 2009), here's what changed and what to do about it.

Existing embeds keep rendering

Old yuml.me/diagram/... URLs in READMEs, blogs, wikis, and docs still produce images today — the original renderer is still running. There's no urgent break to fix.

That said, the original renderer is in maintenance only; all new work (more diagram types, new styles, faster rendering, API keys, the editor) lives on app.yuml.me. Eventually the legacy URL renderer will be retired with plenty of notice.

Move new diagrams to app.yuml.me

The new URL shape:

https://app.yuml.me/diagram/v1/class/clean/[Customer]->[Order].svg

Three things change vs the v1 URL:

• Host: yuml.me → app.yuml.me
• A v1 segment after /diagram/ — this pins the DSL version so future grammar changes won't break embeds
• Type comes before style (v1 was style-first, v2 is type-first)

Style names also moved on a bit — v1's nofunky is now boring, scruffy stays scruffy, and there are new ones (clean, midnight, sketch, napkin, blueprint). See Styles for the full set.

For CI pipelines and high-volume rendering

The free GET endpoint on app.yuml.me is rate-limited per IP (100/hour, 500/day). If you're running a docs generator, build pipeline, or anything that renders at scale, attach an API key:

https://app.yuml.me/diagram/v1/class/clean/[A]->[B].svg?key=yuml_your_api_key

That removes the rate limit and the watermark. API keys require a Pro account — sign up and upgrade, then generate a key from your profile. See Authentication for the full flow.

How It Works

yUML renders diagrams from a simple text-based DSL (domain-specific language). You describe your diagram in a URL or POST body, and yUML returns an image.

The URL format is:

https://app.yuml.me/diagram/v1/{type}/{style}/{dsl}.{format}

Segment	Description	Example
v1	DSL version (always v1)	v1
type	Diagram type	class, sequence, activity, etc.
style	Visual style	clean, plain, sketch, etc.
dsl	URL-encoded diagram text	[A]->[B]
format	Output format	.svg or .png

See the POST API section for the full list of types, styles, and format options.

GET API (Image Embed)

The GET endpoint is designed for <img> tags in public-facing pages — blogs, wikis, READMEs, and documentation.

GET https://app.yuml.me/diagram/v1/{type}/{style}/{dsl}.{svg|png}

The style segment also accepts a ;dir=LR or ;dir=TB modifier to override the default layout direction:

GET https://app.yuml.me/diagram/v1/class/clean;dir=LR/[A]->[B],[B]->[C].svg

The DSL must be URL-encoded. Most characters work as-is, but encode brackets and special characters:

Character	Encoded
[	%5B
]	%5D
#	%23
;	%3B

Response

On success, the API returns the rendered image with caching headers:

200 OK
Content-Type: image/svg+xml
Cache-Control: public, max-age=31536000, immutable
X-Cache: HIT | MISS

On parse error, the API returns 400 with an error message. On rate limit, it returns 429 with a rendered "rate limit reached" image (so embeds degrade gracefully rather than showing a broken image icon).

POST API (Programmatic)

For programmatic use — scripts, CI pipelines, server-side rendering — the POST endpoint accepts JSON and avoids URL-encoding hassles. Authentication is required for production use.

POST https://app.yuml.me/diagram
Authorization: Bearer yuml_your_api_key
Content-Type: application/json

{
  "dsl": "[Customer]->[Order]",
  "type": "class",
  "style": "plain",
  "format": "svg"
}

Field	Required	Default	Values
dsl	Yes	—	Diagram text
type	No	class	class, activity, usecase, sequence, state, journey, journeyflow, roadmap, timeline
style	No	plain	clean, plain, boring, midnight, sketch, napkin, scruffy, blueprint
format	No	svg	svg, png
direction	No	(per-type)	LR, RIGHT, TB, TD, DOWN — see Layout Direction

The response is the raw image bytes with the appropriate Content-Type header.

Example: cURL

curl -X POST https://app.yuml.me/diagram \
  -H "Authorization: Bearer yuml_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"dsl": "[Server]->[Database]", "type": "class", "style": "clean"}' \
  --output diagram.svg

Example: Python

import requests

response = requests.post("https://app.yuml.me/diagram",
    headers={"Authorization": "Bearer yuml_your_api_key"},
    json={
        "dsl": "[Server]->[Database]",
        "type": "class",
        "style": "clean",
        "format": "png"
    }
)

with open("diagram.png", "wb") as f:
    f.write(response.content)

Example: JavaScript

const response = await fetch("https://app.yuml.me/diagram", {
  method: "POST",
  headers: {
    "Authorization": "Bearer yuml_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    dsl: "[Server]->[Database]",
    type: "class",
    style: "clean",
    format: "svg"
  })
});

const svg = await response.text();

Authentication

API access requires a Pro account. Authenticated requests bypass rate limits and remove the watermark from rendered diagrams.

Getting your API key

1. Sign up or upgrade to a Pro plan
2. Click your avatar, then Profile
3. Under API Key, generate a new key

Your key will look like yuml_a1b2c3d4e5f6...

Using your API key

Pass it as a Bearer token in the Authorization header:

Authorization: Bearer yuml_your_api_key

This works with both the GET and POST endpoints. Authenticated requests get:

• No rate limits
• No watermark on rendered diagrams

Styles

Every diagram type supports these visual styles. Pass the style name as a URL segment or in the style field of a POST request.

Output Formats

Format	Extension	Content-Type	Best For
SVG	.svg	image/svg+xml	Web embedding, sharp at any size
PNG	.png	image/png	Documents, emails, chat

Rate Limits

The free API is rate-limited per IP address:

Window	Limit
Per hour	100 renders
Per day	500 renders

When rate-limited, GET requests return a 429 with a rendered image explaining the limit (not a broken image). POST requests return JSON:

{
  "error": "rate_limit_exceeded",
  "retry_after": 3600,
  "message": "Get a free API key at yuml.me/signup..."
}

Headings & Captions

Add a title and description to any diagram with @heading and @caption. These work across all diagram types and styles.

@heading E-Commerce Domain Model
@caption Core entities for order management and delivery
[Customer]->[Order]
[Order]++->[LineItem]

Directive	Description
@heading Your Title	Bold title centred above the diagram
@caption Your description	Smaller text below the diagram, auto-wrapped

If the same directive appears more than once, the last value wins.

Forced line breaks

A literal \n (backslash + the letter n) becomes a forced line break in headings, captions, class-diagram labels and notes, and canvas titles, help text, prose and bullets. Soft-wrapping still applies to each segment, so \n is a guaranteed break, not a substitute for wrapping.

@heading Quarterly Review\nSWOT
[note: Recalculated\non every change]-[Order]

Layout Direction

Most diagram types lay out top-to-bottom by default. The use case diagram is the exception — it goes left-to-right. Override with @direction in the DSL:

@direction LR
[A]->[B]
[B]->[C]

Value	Meaning
LR / RIGHT	Left-to-right
TB / TD / DOWN	Top-to-bottom

Values are case-insensitive. Direction has no effect on diagram types whose layout is intrinsic to the type — sequence, journey flow, timeline, roadmap, and the chart family (bar, column, line, pie).

Per-URL override

If you'd rather not bake direction into the DSL, append it as a modifier on the style segment of the GET URL:

https://app.yuml.me/diagram/v1/class/clean;dir=LR/[A]->[B],[B]->[C].svg

Or pass direction as a field in a POST request. @direction in the DSL and the URL/POST modifier are equivalent; if both are present, the URL or POST value wins.

Class Diagrams

Describe classes and their relationships. Use type: class.

[Customer|name;email|placeOrder()]->[Order|date;total|ship()]
[Order]++-*>[LineItem]

Syntax

Element	Syntax	Example
Class	[Name]	[Customer]
With attributes	[Name|attr1;attr2]	[Customer|name;email]
With methods	[Name|attrs|methods]	[Customer|name|save()]
Stereotype	[<<Interface>>;Name]	[<<Entity>>;Order]
Background colour	[Name{bg:color}]	[Note{bg:yellow}]

Relationships

Relationship	Syntax
Association	[A]->[B]
Inheritance	[A]^[B]
Aggregation	[A]<>->[B]
Composition	[A]++->[B]
Dependency (dashed)	[A]-.->[B]
With labels	[A]label1->label2[B]
With cardinality	[A]1-0..*>[B]

Activity Diagrams

Model workflows and processes. Use type: activity.

(start)->(Receive Order)-><Place Order>->(Process Payment)->(end)

Element	Syntax
Activity	(Activity Name)
Start	(start)
End	(end)
Decision	<Decision>
Fork / join bar	|Bar|
Flow	(A)->(B)
Labelled flow	(A)-[yes]->(B)

Use Case Diagrams

Describe actors and their interactions. Use type: usecase.

[User]-(Login)
[User]-(Browse Catalog)
[Admin]-(Manage Products)

Element	Syntax
Actor	[Actor Name]
Use case	(Use Case Name)
Association	[Actor]-(Use Case)
Extends	(A)<(B)
Includes	(A)>(B)

Sequence Diagrams

Show interactions over time. Use type: sequence.

[Client]request->[Server]
[Server]query->[DB]
[DB]results-->[Server]
[Server]response-->[Client]

Element	Syntax
Object	[Object]
Actor	(Actor)
Synchronous message	[A]msg->[B]
Async message	[A]msg-->>[B]
Return message	[A]msg-->[B]
Alt fragment	{alt condition} ... {else} ... {end}
Loop fragment	{loop condition} ... {end}
Optional fragment	{opt condition} ... {end}

State Diagrams

Model state machines. Use type: state.

(start)->[Idle]
[Idle]-press->[Active]
[Active]-timeout->[Idle]
[Active]-quit->(end)

Element	Syntax
State	[State Name]
Initial state	(start)
Final state	(end)
Transition	[A]-event->[B]
Guarded transition	[A]-event[guard]/action->[B]

C4 Architecture

Software architecture in the C4 style — Context, Container, and Component views from one DSL. Elements carry a type (Person, System, Container, Component, External) that drives colour, iconography, and the avatar strip on People. Use type: c4.

Element	Syntax
Element	[Name|Type|Description]
Relationship	[A]-label->[B]
Dotted / async	[A]-label-.->[B]
Boundary	{Boundary Name ... }

Types (case-insensitive): Person, System, Container, Component, External. Description is optional — leave it blank with a trailing pipe.

C4 System Context Diagram

The top-level view. Shows your software system in its environment — the people who use it and the other systems it talks to. Good for explaining the big picture to non-technical stakeholders.

[Customer|Person|]
[Banking App|System|]
[Email|External|]
[Customer]-Uses->[Banking App]
[Banking App]-Sends mail-.->[Email]

C4 Container Diagram

Zoom in on one system. Shows the deployable containers — web apps, APIs, databases, queues — and how they communicate. “Container” here means a separately runnable unit, not Docker. Wrap child containers in a named boundary.

[Customer|Person|]
{Banking App
  [Web App|Container|]
  [API|Container|]
  [Database|Container|]
}
[Customer]-Uses->[Web App]
[Web App]-Calls->[API]
[API]-Reads/Writes->[Database]

C4 Component Diagram

Zoom into a single container to show its internal components — controllers, services, repositories. This is where the architecture starts to mirror code structure, so keep each diagram focused on one container.

{API Container
  [Auth|Component|]
  [Accounts|Component|]
  [Repository|Component|]
}
[Auth]->[Repository]
[Accounts]->[Repository]

Journey Maps

Visualise user experiences with emotions and a persona card. Use type: journey.

journey: Onboarding
actor: New User
expects: Quick setup

section Sign Up
Find website: :happy:
Create account: :happy:

section First Use
Complete tutorial: :neutral:
Create first item: :elated:

Element	Syntax
Title	journey: Title
Actor	actor: Name
Expectation	expects: Description
Section	section Section Name
Step with emotion	Step name: :happy:
Step with quote	Step name: :happy: "What they said"

Available emotions: :elated: :happy: :relieved: :neutral: :uncertain: :frustrated: :angry:

Journey Flow

A more compact, flowchart-style journey. Uses activity diagram syntax with emoji emotions. Use type: journeyflow.

(Sign Up)->[😊 Find website]->[😊 Create account]->
(First Use)->[😐 Complete tutorial]->[😄 Create first item]

Element	Syntax
Phase	(Phase Name)
Step	[Step text]
Step with emotion	[😊 Step text] or [:happy: Step text]
Speech bubble	["What they said"]
Flow	->

Roadmap Diagrams

Plan features across time horizons. Use type: roadmap.

(Now)
[API Docs|Publish full reference]
[Bug Fixes]
(Next)
[Mobile App|iOS and Android]
(Future)
[AI Features{bg:green}]

Element	Syntax
Horizon / column	(Now), (Next), (Future)
Feature card	[Feature Name]
Card with detail	[Feature|Description]
Card with footer	[Feature|Description|Footer]
Card with colour	[Feature{bg:green}]

Timeline Diagrams

Show milestones over time. Use type: timeline.

(Q1|Research|Gather requirements)->(Q2|Build|Core features)->(Q3|Launch|Public release)

Element	Syntax
Major milestone	(Label|Title|Details)
Minor milestone	[Event name]
Flow	->

Canvas Diagrams

Structured 2D thinking grids — Strategy Cascade, SWOT, Business Model Canvas, retros, OKRs. Markdown-flavoured DSL. Use type: canvas.

@caption Strategic plan for Q4 launch

# Strengths
- Strong engineering bench
- Loyal early customers

# Weaknesses
- Limited marketing budget

# Opportunities
- Underserved SMB segment

# Threats
- Two large incumbents

Canonical headings (Strengths/Weaknesses/Opportunities/Threats, Aspiration/Where to Play/How to Win/Capabilities/Management Systems) are auto-detected — yUML supplies prompt text under each heading and arranges the layout (SWOT → 2×2, Cascade → vertical stack with sub-grids).

Syntax

Element	Syntax	Example
Top-level region	# Title	# Strengths
Sub-region (group child)	## Title	## Geography
Bullet body	- text or * text	- KPI: revenue to £30K
Prose body	any other line	Win the SMB market.
Custom help text	> text	> Where do we win?
Forced line break	\n	# Customer\nAcquisition

Decorators

Decorator	Effect	Example
{cols: N} on a #	Lay out sub-regions in N columns	# Where to Play {cols: 2}
{span: N}	Make a sub-region N times wider	## Channels {span: 2}
{bg: colour}	Fill a single cell with colour	# Aspiration {bg: cornsilk}
{!}	Tint title and body with the theme accent	# Aspiration {!}
@cols N	Set top-level grid width	@cols 3 (BMC)

For AI / LLMs

Building an AI agent, custom GPT, or MCP tool that emits yUML? We publish a compact DSL reference, designed to be pasted directly into a system prompt.

Canonical URL

The spec is versioned with the grammar. v1 is the current stable release.

https://app.yuml.me/dsl/v1/spec       # human-readable HTML
https://app.yuml.me/dsl/v1/spec.txt   # raw plain text for system prompts

Open the HTML spec →  ·  Open the plain-text spec →

Use it from the command line

curl https://app.yuml.me/dsl/v1/spec.txt

Preview the response →

Then prepend the response to your prompt as the system message. Ask the model to produce DSL for any of the diagram types above, render the result via /diagram/v1/{type}/{style}/{dsl}.svg, and you have a working text-to-diagram pipeline.

Versioning

The v1 in the URL matches the DSL grammar version used by /diagram/v1/.... If the grammar ever breaks backwards compatibility, a new spec ships at /dsl/v2/spec and the v1 URL stays stable for agents already pinning it.

What's in the spec

Syntax reference for every supported diagram type (class, sequence, activity, use case, state, C4, journey, journey flow, timeline, roadmap), plus story format, common metadata directives (@heading, @caption, @legend), and a "common mistakes to avoid" section.

Maintained where the grammar lives

The spec is the single source of truth across our editor's "Fix with AI" feature, our MCP server's tool descriptions, and these docs. Edit one file, all three update.

FAQ

What is yUML?

yUML is an online tool for creating diagrams from simple text. Describe your diagram in a URL or POST body, and yUML renders it as SVG or PNG. No desktop software needed.

Is it free?

Yes. The rendering API is free with generous rate limits (100/hour, 500/day). Cache hits don't count, so embedding the same diagram everywhere is effectively unlimited.

What diagram types are supported?

Class, activity, use case, sequence, state, C4 architecture, journey map, journey flow, roadmap, and timeline. See the diagram types section above for syntax details.

Can I use yUML in my app or tool?

Absolutely. The API is designed for embedding and programmatic use. Use the GET endpoint for <img> tags on public pages, or the POST endpoint for scripts and server-side rendering.

How do I use special characters like # or ;?

URL-encode them: # becomes %23, ; becomes %3B. Or use the POST API where the DSL is in JSON and doesn't need URL encoding.

What is UML?

Unified Modelling Language — a standard notation for software diagrams. yUML supports a practical subset, plus non-UML types like journey maps and roadmaps. Learn more on Wikipedia.

Where can I try it?

The Playground lets you write and preview diagrams interactively.