Create and secure embeds

Mint a public worksheet URL, restrict where it can be framed, and understand caching and revocation.

Audience: Web application and LMS integrators
Before you start: A server-side API key and a list of sites that should be allowed to frame the worksheet

Mint an embed

POST /embeds generates a fixed worksheet, stores it, and returns embedId plus embedUrl. A completed mint uses credit blocks; subsequent views are free.

curl -X POST "https://overthemathwall.com/api/public/v1/embeds" \
  -H "Authorization: Bearer $OTMW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seed": 42,
    "locale": "en",
    "title": "Warm-up",
    "showAnswerKey": false,
    "allowedDomains": ["example.com", "*.school.edu"],
    "entries": [
      {"id":"warmup-1","grade":"grade3","topic":"multiplication","difficulty":"easy","count":5}
    ]
  }'

<iframe
  src="https://overthemathwall.com/embed/emb_..."
  width="100%"
  height="800"
  title="Math worksheet"
></iframe>

Allowed domains and CSP

Omit allowedDomains to let any site frame the URL.
Include up to 20 hosts; patterns such as example.com, *.example.org, and hosts with a development port are accepted.
The list becomes the CSP frame-ancestors directive alongside 'self'. Test the exact domain and its subdomains: a wildcard does not necessarily include the apex domain.

Answers and data

When showAnswerKey is true, any visitor to the URL can see the answers. Do not use an embed for secret assessments. Do not include student names, identifiers, or other personal data in the title or in systems constructing the request.

Caching and revocation

The generated worksheet is stored with the embed so public views do not regenerate content. The public response may be cached for up to five minutes. Consequently, revocation can take up to five minutes to appear across caches. Revoked and unknown URLs return the same 404.

There is no public operation to edit an embed. To change content, answers, or domains, mint a replacement, update your iframe, and revoke the previous embed.