Developer documentation

PersonWise oEmbed

Turn a public PersonWise course URL into a responsive, voice-interactive player without asking authors to paste iframe HTML.

Endpoint

Send an HTTP GET request. JSON is the supported response format; url is required, while maxwidth and maxheight are optional positive pixel constraints.

https://personwise.ai/api/oembed

Supported URL scheme

https://personwise.ai/t/*/public

Only link-accessible PersonWise public-course pages resolve. Private, withdrawn, unavailable, and unknown courses return a not-found response.

Example request

https://personwise.ai/api/oembed?url=https%3A%2F%2Fpersonwise.ai%2Ft%2F1646a8a8%2Fpublic&format=json&maxwidth=800

Example response

{
  "version": "1.0",
  "type": "rich",
  "provider_name": "PersonWise",
  "title": "Example interactive course",
  "width": 800,
  "height": 450,
  "html": "<iframe src=\"https://personwise.ai/embed/1646a8a8\" ...></iframe>"
}

Provider behavior

The endpoint parses only PersonWise course URLs and never fetches a caller-supplied origin.
Representations preserve 16:9 and honor maxwidth and maxheight.
The iframe requests microphone and autoplay permissions; hosts that remove them receive the player’s built-in fallback.
Resolved course pages advertise the endpoint with application/json+oembed discovery metadata.