# Describe a diagram link for an embedder (oEmbed)

> Page: https://docs.plotwork.dev/api/get-oembed. Index of every page: https://docs.plotwork.dev/llms.txt

The oEmbed endpoint for Notion, Slack, wikis and other embedders.

`GET /oembed`

## TL;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`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#oembedphoto) |
| 400 | The query is not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | The address is not a Plotwork diagram link, or it shows nothing now. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 501 | A format other than json; only json is answered. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Hosting is not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`OEmbedPhoto`](https://docs.plotwork.dev/api/schemas.md#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](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |