Embed cards and badges
Put a prompt, skill, blog post, challenge or creator profile on your own site as a card, or a prompt or skill in a README as a badge. Every card links back to the item on Prompt Dock.
In this guide
How to embed
- Open the item's Share menu and choose Embed this prompt (or Embed this skill, Embed this blog post, Embed this challenge, Embed this profile).
- Pick where you'll paste it. The dialog shows the one snippet that works there.
- Pick a size and a theme (Light, Dark, Match the reader's device), check the preview, then Copy.
- Paste it on your site, in the place the steps below name.
Where the Share menu is:
- A prompt, skill or blog post: the Share menu on its page in your dashboard, or on its public page.
- A challenge: the Share menu in its detail view, or on its public page.
- Your profile: Share profile on your public profile page, or in Settings, Profile, beside your public URL.
Only published, public items can be embedded. When one can't be, the menu says why instead, for example:
- Publish this to embed it.
- You can embed this once it's approved.
- Make this public to embed it.
Sizes
Each size has a fixed height and fits any frame from its minimum width up to its widest. These numbers are a permanent contract: a frame pasted on another site keeps the height it was pasted with, so they never change. A new layout comes as a new size.
| Size | Height | Minimum width | Widest | What it shows |
|---|---|---|---|---|
| Small | 96px | 280px | 560px | A slim bordered card: the title, one line of description, who made it, and a button. No image. |
| Medium (default) | 380px | 280px | 420px | The cover with a type pill (and the Free or Premium pill on a prompt or skill), the title, two lines of description, and a footer with the creator and a button. |
| Large | 540px | 280px | 480px | Everything: the cover, the creator, the title, the description, the model and rating chips, the counts, a skill's install command, and a full-width button. |
A count shows once it reaches 10, and a rating once it has 5 ratings, so a new item's card is not a row of zeros. A profile's counts and a challenge's solution count always show.
The URLs
Every snippet points at one of these paths, and they are part of the same contract: a snippet pasted on another site keeps the paths it was pasted with.
| What | Path | Values |
|---|---|---|
| Card | /embed/<type>/<id>/<size>/<theme> | type prompt, skill, blog, challenge, profile; size s, m, l; theme light, dark, auto |
| Badge | /badge/<type>/<id>/<theme>.svg | type prompt, skill; theme light, dark |
| oEmbed | /oembed?url=&maxwidth=&maxheight=&format=&theme= | the keys in that order; empty ones left out |
| Click hop | /embed/go/<type>/<id>/<size>/<target> | type prompt, skill, blog, challenge, profile; size s, m, l, b; target action, creator, badge. Size b and target badge always go together, on a prompt or skill only; creator is never on a profile. The badge snippets link through it, and it answers a redirect that is never cached. |
| Item page | /prompt/<id>, /skill/by-id/<id>, /blog/<id>, /challenges/<id>, /u/by-id/<id> | The link under the frame and the Page link. A skill's and a profile's by-id link answers a permanent redirect to its current page, so a new handle or slug never breaks it. |
The id is a lowercase uuid. Any other spelling of a path (an uppercase id, a missing or unknown size or theme, extra segments, a query string) is answered with a permanent redirect to the canonical one, before anything is read: a missing size is m and a missing theme light.
Where to paste it
Each site takes one snippet form. The dialog picks it when you choose the site; the steps are the same as here. A site shows as checked only once a published page there shows the card working.
WordPress
HTML snippet · Custom HTML block. Not checked yet.
- In the block editor, add a Custom HTML block.
- Paste the HTML snippet into it.
- Preview the post to check the card.
A pasted link shows the card, but its links don't open. Use a Custom HTML block.
Ghost
HTML snippet · HTML card. Not checked yet.
- In the editor, type / and choose HTML.
- Paste the HTML snippet into the card.
Notion
Embed link · Embed block. Not checked yet.
- Type /embed and press Enter.
- Paste the embed URL and choose Embed link.
Webflow
HTML snippet · Code Embed element. Not checked yet.
- Add a Code Embed element to the page.
- Paste the HTML snippet and save.
Framer
HTML snippet · Embed component, HTML tab. Not checked yet.
- Add an Embed component to the page.
- Choose HTML and paste the HTML snippet.
- Size the component to the card.
GitHub
README badge · README. Not checked yet.
- Open your README.md.
- Paste the badge snippet where you want it.
Prompts and skills only. The badge follows the reader's light or dark theme.
Other
HTML snippet · HTML. Not checked yet.
- Paste the HTML snippet where the site accepts HTML.
The snippet forms
The HTML snippet is a frame plus one plain link to the item under it, so a site that strips frames still links back. The Embed link is the frame's address alone, for sites that build the frame themselves. The Page link is the item's own address, for sites that turn a pasted link into a card through oEmbed. The dialog fills in your item; <id> below stands for its id.
HTML snippet
<iframe src="https://www.promptdock.ai/embed/prompt/<id>/m/light" title="Prompt: Example prompt on Prompt Dock" width="100%" height="380" style="display:block;max-width:420px;border:0" frameborder="0" scrolling="no" loading="lazy" referrerpolicy="strict-origin-when-cross-origin" sandbox="allow-popups allow-popups-to-escape-sandbox"></iframe>
<a href="https://www.promptdock.ai/prompt/<id>">"Example prompt" on Prompt Dock</a>Embed link
https://www.promptdock.ai/embed/prompt/<id>/m/lightPage link
https://www.promptdock.ai/prompt/<id>README badge
The badge is 20px tall, for prompts and skills only, and links through Prompt Dock to the item. A free prompt's badge says what the reader can do there; a premium item's says it is premium, never "free". Once the lead count (uses for a prompt, installs for a skill) reaches 10, the badge shows it.
| Type | Free | Premium |
|---|---|---|
| prompt | Run free | Premium prompt |
| skill | Install | Premium skill |
On GitHub use the README badge: it carries a light and a dark badge and shows the one that matches the reader's theme. GitHub's dark background hides part of the light badge, which is why the dark one is there. Anywhere else that takes Markdown, the Markdown badge shows the light badge.
README badge
<a href="https://www.promptdock.ai/embed/go/prompt/<id>/b/badge"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.promptdock.ai/badge/prompt/<id>/dark.svg"><img alt="Run Example prompt free on Prompt Dock" src="https://www.promptdock.ai/badge/prompt/<id>/light.svg" height="20"></picture></a>Markdown badge
[](https://www.promptdock.ai/embed/go/prompt/<id>/b/badge)oEmbed
For sites and services that build a card from a link. The endpoint is https://www.promptdock.ai/oembed.
Request
| Parameter | Meaning |
|---|---|
| url | Required. An item's page on Prompt Dock, its embed URL, or its dashboard URL (below). |
| maxwidth | Optional. The widest the card may be, in pixels. |
| maxheight | Optional. The tallest the card may be, in pixels. |
| format | Optional. json, the only format. |
| theme | Optional. light, dark, auto; light when left out. |
Send the parameters in that order with the empty ones left out; any other order is answered with a permanent redirect to it.
A request
https://www.promptdock.ai/oembed?url=https%3A%2F%2Fwww.promptdock.ai%2Fprompt%2F<id>&format=jsonAccepted URLs
On www.promptdock.ai or promptdock.ai, over https:
| Path | What it is |
|---|---|
| /prompt/<id> | a prompt's public page |
| /skill/<handle>/<slug> | a skill's public page |
| /skill/by-id/<id> | a skill's stable link |
| /blog/<slug or id> | a blog post |
| /challenges/<id> | a challenge |
| /u/<handle> | a creator profile |
| /u/by-id/<id> | a profile's stable link |
| /embed/<type>/<id>/<size>/<theme> | an embed URL; its size and theme are honoured |
| /dashboard/prompt/<id> | a prompt in the dashboard |
| /dashboard/skill/<id> | a skill in the dashboard |
| /dashboard/blog?post=<id> | a post in the dashboard reader |
| /dashboard/challenges/<id> | a challenge in the dashboard (also ?open=<id>) |
Choosing a size
A size fits when maxwidth is at least its minimum width and maxheight at least its height; a value that is missing, zero, negative or not a number is ignored. The answer is Medium when it fits, otherwise the largest size that fits. width is that size's widest, capped at maxwidth; height is its fixed height. When nothing fits, the answer is a link instead of a card.
| maxwidth | maxheight | Answer |
|---|---|---|
| not sent | not sent | type "rich", Medium, width 420, height 380 |
| 320 | not sent | type "rich", Medium, width 320, height 380 |
| not sent | 379 | type "rich", Small, width 560, height 96 |
| 279 | not sent | type "link": the metadata with no html |
Response
| Field | Meaning |
|---|---|
| type | "rich" when a size fits; "link" when none does, with no html. |
| version | "1.0". |
| html | The iframe alone. The visible link under it belongs to the copied snippet, not to this answer. |
| width | The chosen size's widest, capped at maxwidth. |
| height | The chosen size's fixed height (the iframe's). |
| title | The item's title. |
| author_name | The creator's name. |
| author_url | The creator's profile, by its stable link, only when they have a public profile. |
| provider_name | "Prompt Dock". |
| provider_url | Prompt Dock's origin. |
| thumbnail_url | The item's social card, with thumbnail_width 1200 and thumbnail_height 630. Left out for skills, and when maxwidth or maxheight is smaller. |
| cache_age | 300 (seconds). |
Errors
An error is a JSON body, { "error": "<code>" }, with this status. An item that does not exist and one that can't be embedded get the same answer, so the endpoint never reveals a private item.
| Code | Status | Meaning |
|---|---|---|
| missing_url | 400 | The url parameter is missing. |
| unsupported_url | 404 | The url is not a Prompt Dock page that can be embedded. |
| not_found | 404 | No public item at that url, or embeds are switched off. |
| format_not_supported | 501 | Only format=json is supported. |
| rate_limited | 503 | Too many requests; retry after the Retry-After seconds. |
| unavailable | 503 | The item could not be read; retry shortly. |
Caching, limits and CORS
| Response | Headers |
|---|---|
| A card, a badge, or an oEmbed answer with status 200, 400, 404 or 501 | Cache-Control: public, max-age=60Vercel-CDN-Cache-Control: max-age=180 |
| A card or badge whose item could not be read | Cache-Control: public, max-age=0Vercel-CDN-Cache-Control: max-age=60 |
| Over a limit, an oEmbed 503, and every click through a card | Cache-Control: no-store |
Each caller address may ask about one item 120 times a minute, and 1200 times a minute in all. Over either, the answer is rate_limited with a Retry-After header.
The endpoint sends no CORS header, so a browser page cannot read it directly. Fetch it from your server, as every host above does.
While embedding is on, every public item page and every embed URL carries a <link rel="alternate" type="application/json+oembed"> pointing at this endpoint, so a host that discovers oEmbed from a pasted link finds it.
The sandbox attribute
The HTML snippet sets sandbox="allow-popups allow-popups-to-escape-sandbox". Keep it.
- The card is plain HTML and CSS: no script, no form, no cookie. The sandbox keeps it that way on your page whatever happens.
- allow-popups lets a reader's click open Prompt Dock in a new tab, and allow-popups-to-escape-sandbox lets that tab work normally. Nothing else is allowed: no script, no form, no navigation of your page, no access to it.
- Keep the width and height the snippet sets. A frame does not resize itself, and each size's height is fixed, so the card always fits it.
The snippet sets referrerpolicy="strict-origin-when-cross-origin", so Prompt Dock learns the name of the site a card shows on, and never the page's full address.
Embed URLs are the only Prompt Dock pages a site may frame. Every other page refuses to be framed.
Taking an item down
- When an item is unpublished, made unlisted, hidden or removed, new loads of its card, its badge and its oEmbed answer stop showing it within 5 minutes and show a neutral card that links to Prompt Dock instead.
- A frame already open on a reader's screen keeps the card until they reload the page.
- The link under the frame is the host page's own text, so it stays until that site's owner edits the page.
- A copy someone else made can last longer: GitHub serves README badges through its own image proxy, and a site that stored an oEmbed thumbnail keeps it until it refreshes.
What an embed earns
An embed earns nothing by itself. A reader who follows a card to Prompt Dock and unlocks, installs or reads there is what the creator pool counts. The Copy embed dialog shows the item's creator the note for its type:
- prompts. Your share of the creator pool comes from premium-prompt unlocks on Prompt Dock. Free prompts build reach; they don't earn. Views on your site don't count; activity on Prompt Dock does.
- skills. Your share of the creator pool comes from skill views and installs on Prompt Dock. Views on your site don't count; activity on Prompt Dock does.
- blogs. Your share of the creator pool comes from blog reads on Prompt Dock. Views on your site don't count; activity on Prompt Dock does.
Challenges and profiles don't earn from the creator pool, so their dialog shows no note. How the pool works: Earnings and payouts.
Privacy
- An embed sets no cookie and runs no script: the card is plain HTML and CSS, and the badge is an image.
- Showing a card records no view, unlock, read or install, for anyone.
- Prompt Dock counts, per day, how many readers clicked a card or badge (by item, size and what was clicked), how often a creator copied a snippet, and the names of the sites a card shows on, taken from the browser's Referer header. Never an IP address, a visitor id, a cookie or a page's full address.
- The site names come from the Referer header, which the reader's browser sends and any program can set. So they are a lower bound (a load served from the cache, or one without a Referer, names no site) and can also include a site a card never showed on. Each item records at most 50 new site names a day.
- Those counts are kept for 400 days.