Organisations

Upload or replace a custom icon

Saves one SVG or PNG icon (at most 32 KB) under a name diagrams use as icon=org: on the hosted service, with up to ten aliases.

PUT/orgs/{org}/icons/{name}

TL;DR

Question	Answer
What does it do?	Upload or replace a custom icon.
What does it take?	A JSON body of type `IconBody`.
What does it return?	Status 200 with a body of type `SavedIcon`.
What can go wrong?	`400` the body is not valid; `401` not signed in; `403` the caller's role may not (orgs.forbidden), the owner's plan does not include custom icons (plan.icons_not_included), the organisation holds the most icons it may (orgs.icon_limit_reached), or the request came from an origin that may not make changes; `404` no such organisation, or the caller is not a member of it; `413` the body is too large; `422` the file, the name or an alias does not check (icon.invalid, with every issue in details); `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope.

What it does

Saves one SVG or PNG icon (at most 32 KB) under a name diagrams use as icon=org: on the hosted service, with up to ten aliases. An SVG is rewritten from an allowlist; anything that could run or load is refused. The owner and admins may, on a plan with custom icons. 422 icon.invalid carries every issue.

Path parameters

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.
`name`	`string`	yes	The name after org:, lowercase words joined by hyphens.

Request body

The body has the type IconBody.

Field	Type	Required	Description
`svg`	`string`	no	The SVG file's text, at most 32 KB. It is rewritten from an allowlist before it is stored. at most 49152 characters.
`png`	`string`	no	The PNG file's bytes in base64, at most 32 KB and 1024 pixels on a side. at most 49152 characters.
`aliases`	`string[]`	no	Other names search and automatic matching find the icon by, at most 10. Left out, the icon has none.

Responses

Status	Meaning	Body
200	The saved icon, and what the check left out of the file.	`SavedIcon`
400	The body is not valid.	`ErrorResponse`
401	Not signed in.	`ErrorResponse`
403	The caller's role may not (orgs.forbidden), the owner's plan does not include custom icons (plan.icons_not_included), the organisation holds the most icons it may (orgs.icon_limit_reached), or the request came from an origin that may not make changes.	`ErrorResponse`
404	No such organisation, or the caller is not a member of it.	`ErrorResponse`
413	The body is too large.	`ErrorResponse`
422	The file, the name or an alias does not check (icon.invalid, with every issue in details).	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Organisations are not set up on this server.	`ErrorResponse`

Response body

A 200 answer has the type SavedIcon.

Field	Type	Required	Description
`icon`	`OrgIcon`	yes
`icon.name`	`string`	yes
`icon.ref`	`string`	yes	What a diagram writes to use it.
`icon.aliases`	`string[]`	yes
`icon.mediaType`	`"image/svg+xml" \| "image/png"`	yes
`icon.image`	`string`	yes	The checked picture as a data: address, for a preview.
`icon.width`	`number`	yes
`icon.height`	`number`	yes
`icon.bytes`	`integer`	yes
`icon.updatedAt`	`integer`	yes	Milliseconds since the epoch.
`removed`	`string[]`	yes	What the check left out of the file because it draws nothing, such as editor metadata.

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools