SpyBara
Go Premium

annotations-extensibility.md 2026-10-06 23:02 UTC to 2026-10-07 23:57 UTC

This page contains 337 additions and 63 deletions.

2026
Wed 7 23:57 Thu 8 23:01

Annotations Extensibility

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

The Browser Annotation API lets your website customize what people select, what context accompanies their feedback, and which controls they use to preview changes before sending an annotation to ChatGPT.

The Browser Annotation API isn't currently available in ChatGPT Enterprise or Edu workspaces.

Browser annotations work on your site without any code changes. People can select part of a page, add a comment, and send it in Context to Codex or ChatGPT Work.

As a developer, you can use the Browser Annotation API to provide context or controls specific to your application. For example, you can attach previews for component variants in a design system preview for developers to know how to update the components on a website.

To get help understanding the Browser Annotation API or adding annotation support to your website, install the Annotations Extensibility plugin.

Install the Annotations Extensibility plugin

Try it

See the Browser Annotation API in action on this guide.

  1. Open this page in ChatGPT's built-in browser.
  2. Try opening the suggested prompt that will appear in this card.
  3. Enter Annotation mode, then select the table below or a code sample to switch between predefined layouts and themes.
  4. You can still annotate any item on the page and see default annotation behavior.

Open in ChatGPT's browser

Choose what to customize

Start with the integration that fits your website:

Goal Integration
Make a card or other group of elements selectable as one object Selection targets
Let people select a phrase or sentence Text selection containers
Include additional context with a selection Selection metadata
Open an annotation from your own button with a suggested comment Annotation requests
Request feedback on an exact passage from your own UI Text-range requests
Show advanced controls when an annotation opens Editor defaults
Preview application properties or collect choices Custom controls
Select individual objects drawn inside a canvas Annotation surfaces
Turn Annotation mode on or off from your site Annotation mode controls

This guide targets the DevDay 2026 release of the ChatGPT desktop app and later. The JavaScript API is available through document.oai.annotation in the app's built-in browser, on secure, top-level pages such as HTTPS or localhost. When enabled, the browser installs it before your page's scripts run. Feature-detect each method to support older or unsupported browsers, then initialize your integration once its DOM elements exist. No readiness event or polling is needed.

API methods return synchronously, and registration handles are ready to use immediately. The browser can finish loading the annotation editor afterward. A surface's hitTest callback can return a promise.

Customize selection targets

By default, Annotation mode selects elements from the page's DOM, favoring targets such as text, images, and controls. To make a larger object selectable, mark its containing region with oai-annotation-container and its selectable descendants with oai-annotatable.

This example makes a chart card selectable as one object:

<section oai-annotation-container>
  <article id="chart-card" oai-annotatable="Q3 Revenue">
    <h2>Q3 Revenue</h2>
    <p>$120,000 this quarter</p>
    <button type="button">More info</button>
  </article>
</section>

Pointing anywhere within the card highlights the entire card. The optional oai-annotatable value gives the object a name shown to the user and the model. Choose names that distinguish nearby objects, or omit the value.

The container defines where these selection rules apply. An oai-annotatable attribute on its own doesn't change selection behavior. Within a container, the browser selects the nearest marked target containing the element under the pointer. Nested containers use the nearest container. Unmarked areas inside a container create a webpage annotation; areas outside all containers keep the default behavior.

Enable text selection

Add oai-annotation-container-text to a region to let people drag to select text during Annotation mode. The attribute doesn't need a value:

<article oai-annotation-container-text>
  <h2>Design guidelines</h2>
  <p>Use consistent spacing between related components.</p>
  <p>Leave more space between separate groups.</p>
</article>

Releasing a nonempty selection opens the text annotation editor with the selected range and its context. Clicking without selecting text doesn't create an annotation. Escape or a canceled gesture cancels the selection.

The nearest text or DOM selection container determines how a gesture begins. Text containers don't use oai-annotatable markers for element picking. Nest an oai-annotation-container to restore element picking, or a text container to restore text selection. If both attributes are on one element, text selection takes precedence.

Text selection follows the page's normal selection rules and can extend beyond the starting container. A container doesn't clip the range or enable selection inside an iframe. Text fields remain selectable, but ordinary page clicks and native actions on controls remain blocked during Annotation mode. Explicit request() calls keep their existing behavior.

Text selection containers take effect only during Annotation mode when the site annotation capability and per-site setting are enabled.

Add context to a selection

Add oai-annotation-metadata to a marked target to include context that may not be visible on the page. For example, a fictional contact row can include an email address for a request to draft an email:

<section oai-annotation-container>
  <div
    id="contact-row"
    oai-annotatable="Alex Morgan"
    oai-annotation-metadata='{"email":"alex@example.com"}'
  >
    <div>Alex Morgan</div>
    <div>Project lead</div>
  </div>
</section>