Hosting
Describe a diagram link for an embedder (oEmbed)
The oEmbed endpoint for Notion, Slack, wikis and other embedders.
GET
/oembedTL;DR
| Question | Answer |
|---|---|
| What does it do? | Describe a diagram link for an embedder (oEmbed). |
| What does it take? | url, format, maxwidth, maxheight in the query string. |
| What does it return? | Status 200 with a body of type OEmbedPhoto. |
| What can go wrong? | 400 the query is not valid; 404 the address is not a plotwork diagram link, or it shows nothing now; 429 too many requests; 501 a format other than json; only json is answered; 503 hosting is not set up on this server. Every failure uses the one error envelope. |
What it does
The oEmbed endpoint for Notion, Slack, wikis and other embedders. Give it a stable link, a picture link, or a viewer page, and it answers a photo: the public SVG, its size (scaled to maxwidth and maxheight), the title "Diagram" and no author. For a stable link the picture is the stable link itself, so the embed keeps showing the latest version. Only format=json; another format is a 501. An address that is not a Plotwork diagram link, or shows nothing now, is a 404.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | A stable link, a picture link, or the viewer page of a picture. |
format | string | no | Only json is answered; any other format is a 501, as the specification asks. |
maxwidth | integer | no | The widest the picture may be, in pixels. |
maxheight | integer | no | The tallest the picture may be, in pixels. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The oEmbed answer. | OEmbedPhoto |
| 400 | The query is not valid. | ErrorResponse |
| 404 | The address is not a Plotwork diagram link, or it shows nothing now. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 501 | A format other than json; only json is answered. | ErrorResponse |
| 503 | Hosting is not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type OEmbedPhoto.
| Field | Type | Required | Description |
|---|---|---|---|
version | "1.0" | yes | |
type | "photo" | yes | |
provider_name | string | yes | |
provider_url | string | yes | |
title | string | yes | Always "Diagram": the diagram's own name is shown only to its owner. |
url | string | yes | The picture. For a stable link, the stable link itself, so the embed keeps showing the latest version. |
width | integer | yes | |
height | integer | yes | |
cache_age | integer | yes | Seconds the answer may be kept: 60 for a stable link, 3600 for a picture. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |