app.bsky.embed.getEmbedExternalView
#main
Resolve one AT-URI record into the data needed to render an enhanced external embed. The records are validated against the requested url before any view is built. When validation passes, returns data, associatedRefs (strongRefs to embed into a post's external.associatedRefs) and the raw associatedRecords, plus a legacy view for Standard.site records only. When validation fails, only unverifiedAssociatedRefs and unverifiedAssociatedRecords are returned and no view or data is built. The response is empty ({}) when no record URI was usable or the record could not be resolved; clients should fall back to their own link-card rendering in that case and skip writing strongRefs to the post.
Parameters
| Property | Type | Known Values | Required | Description |
|---|---|---|---|---|
| url | string (uri) | - | ✅ | The canonical web URL the embed represents (typically the URL the user pasted into the composer). Used as the returned view's uri, and validated against the resolved records. |
| canonicalUri | string (at-uri) | - | ❌ | The canonical AT URI of the atproto record found on the webpage. When provided, takes precedence over uris, which is then ignored. |
| uris | array of at-uri | - | ❌ | - |
Output
- Encoding: application/json
| Property | Type | Known Values | Required | Description |
|---|---|---|---|---|
| view | app.bsky.embed.external#view | - | ❌ | - |
| data | union of app.bsky.embed.external#viewArticle app.bsky.embed.external#viewArticlePublication app.bsky.embed.external#viewGallery app.bsky.embed.external#viewLivestream | - | ❌ | - |
| associatedRefs | array of com.atproto.repo.strongRef | - | ❌ | StrongRefs (URI+CID) of the Atmosphere records selected for persistence in a post, suitable for embedding into its external.associatedRefs: the canonical record, plus only the additional records the service chooses to persist for its collection. This can be a subset of the records used to render data, which may also draw on other hydrated records such as recommendations, subscriptions, or favorites. Present only when validation passed. Index-aligned with associatedRecords. |
| associatedRecords | array of unknown | - | ❌ | - |
| unverifiedAssociatedRefs | array of com.atproto.repo.strongRef | - | ❌ | StrongRefs (URI+CID) of the same persistence-selected Atmosphere records (the canonical record plus chosen additional records) when validation of the requested url failed. These must not be written to a post. Index-aligned with unverifiedAssociatedRecords. |
| unverifiedAssociatedRecords | array of unknown | - | ❌ | - |