Organisations

Show a private diagram on chosen websites

Makes an embed link.

POST/orgs/{org}/diagrams/{id}/embed-links

TL;DR

Question	Answer
What does it do?	Show a private diagram on chosen websites.
What does it take?	A JSON body of type `CreateEmbedLinkBody`.
What does it return?	Status 201 with a body of type `EmbedLink`.
What can go wrong?	`400` a website is not a host name (orgs.embed_link_sites_invalid), or the end is not allowed (orgs.embed_link_expiry_invalid); `401` not signed in; `403` not on the plan (plan.embed_links_not_included), the setting is off (orgs.embed_links_off), the role may not (orgs.forbidden), the diagram holds a secret the organisation blocks (orgs.publish_blocked), or the request came from an origin that may not make changes; `404` no such organisation, diagram or link, or the caller is not a member, or the diagram is in a folder the caller may not use; `409` labelled Confidential (orgs.embed_link_classified), waiting for approval (orgs.diagram_pending), or five links already (orgs.embed_link_limit_reached); `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope.

What it does

Makes an embed link. A page on one of its websites gets the picture without its source; anything else gets a placeholder. The site is read from Origin or Referer, so it stops casual reuse and is not access control. Enterprise, while the owner allows it, never for a Confidential diagram.

Path parameters

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.
`id`	`string`	yes

Request body

The body has the type CreateEmbedLinkBody.

Field	Type	Required	Description
`sites`	`string[]`	yes
`expiresAt`	`integer \| null`	no	When it stops, in milliseconds since the epoch, within three years. Left out or null: never.
`label`	`string \| null`	no	An optional name for the page it is for. at most 80 characters.

Responses

Status	Meaning	Body
201	The link, with its address.	`EmbedLink`
400	A website is not a host name (orgs.embed_link_sites_invalid), or the end is not allowed (orgs.embed_link_expiry_invalid).	`ErrorResponse`
401	Not signed in.	`ErrorResponse`
403	Not on the plan (plan.embed_links_not_included), the setting is off (orgs.embed_links_off), the role may not (orgs.forbidden), the diagram holds a secret the organisation blocks (orgs.publish_blocked), or the request came from an origin that may not make changes.	`ErrorResponse`
404	No such organisation, diagram or link, or the caller is not a member, or the diagram is in a folder the caller may not use.	`ErrorResponse`
409	Labelled Confidential (orgs.embed_link_classified), waiting for approval (orgs.diagram_pending), or five links already (orgs.embed_link_limit_reached).	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Organisations are not set up on this server.	`ErrorResponse`

Response body

A 201 answer has the type EmbedLink.

Field	Type	Required	Description
`id`	`string`	yes
`diagramId`	`string`	yes
`url`	`string \| null`	yes	The address, `{EMBED_URL}/o/<token>.svg`. A page on one of `sites` that shows it as an image gets the picture, without its source; anything else gets a placeholder. Null when the server cannot show it again: rotate the link for a new one.
`label`	`string \| null`	yes	An optional name for the page it is for.
`sites`	`string[]`	yes	The websites a page must be on, lower case.
`proxiedSites`	`string[]`	yes	Sites in `sites` whose images reach Plotwork through a proxy that names no page (GitHub), so the link shows them the placeholder.
`expiresAt`	`integer \| null`	yes	When it stops, in milliseconds since the epoch, or null for never.
`expired`	`boolean`	yes
`createdBy`	`string \| null`	yes
`createdAt`	`integer`	yes
`updatedAt`	`integer`	yes
`rotatedAt`	`integer \| null`	yes

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