Documentation

Quick Start

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

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

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

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://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://yuml.me/diagram/v1/{type}/{style}/{dsl}.{svg|png}

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://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

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

Example: cURL

curl -X POST https://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://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://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..."
}

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]

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	->

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, 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.