Conversation Exporter — Reference Architecture

There isn't a single "best" approach — it depends on how much control you have. Here's the practical hierarchy, from most to least reliable. ## 1. Backend API endpoint (most reliable) ChatGPT's web client fetches conversations from an internal JSON endpoint. If you grab the conversation payload directly, you get clean structured data instead of scraping rendered HTML. The rough shape: ``` GET https://chatgpt.com/backend-api/conversation/ Authorization: Bearer ``` You can obtain the token from the session endpoint the app itself uses (`/api/auth/session`), which returns JSON containing an `accessToken` field. Because you're running inside the page context (userscript or devtools console), cookies are sent automatically. The response contains a `mapping` object: a tree of message nodes keyed by UUID, each with `parent`, `children`, and a `message` object holding `author.role`, `content.parts`, `create_time`, and metadata. To reconstruct the visible thread you walk from `current_node` up through parents, then reverse. **Do not** just iterate `Object.values(mapping)` — that includes abandoned branches from edits and regenerations, so you'll get duplicate or contradictory turns. Advantages: stable-ish field names, no CSS dependency, includes timestamps and model slugs, gives you code blocks with original markdown intact. Caveats: it's undocumented and unversioned, so it can change without notice. Rate-limit yourself if iterating many conversations. Treat the access token as a secret — never log it or send it anywhere. ## 2. DOM scraping (fallback) Necessary if you can't get a token or you're targeting a shared/public conversation link. Key points: - Anchor on `data-message-id`, `data-message-author-role`, and `data-testid` attributes rather than class names. Tailwind-generated classes churn constantly; the data attributes have been comparatively durable. - The message list is virtualized in long threads. You must scroll to force render, or read from the embedded hydration payload instead. For shared links, look for a `__NEXT_DATA__` script tag or a `__reactRouterContext.streamController` payload — often the whole conversation is sitting there as JSON, which lets you skip scraping entirely. - Convert HTML back to Markdown with something like Turndown, plus the GFM plugin for tables and strikethrough. Handle `

` specially so fences keep their language hint.
- Strip UI chrome: copy buttons, "thumbs up/down" controls, avatar text, the `sr-only` accessibility labels.

## 3. Print-to-PDF / CSS print stylesheet

Lowest effort, genuinely useful for archival. Inject a print stylesheet that hides the sidebar, composer, and buttons, unsets `overflow: hidden` on scroll containers, and adds `break-inside: avoid` to code blocks. Then `window.print()`. Lossy for reuse but resilient.

## Structural advice regardless of approach

Write a thin **adapter layer** that normalizes to your own schema:

```js
{ id, title, model, createdAt, messages: [{ role, text, createdAt, meta }] }
```

Everything downstream (Markdown writer, JSON writer, HTML writer) consumes only that schema. When ChatGPT changes, you fix one adapter function instead of your whole tool.

Add a **cheap self-check**: assert message count > 0, alternating-ish roles, no empty bodies. If assertions fail, fall back to the next strategy rather than silently emitting a broken file. Log which strategy succeeded so you can tell when the primary path rots.

Prefer a **userscript** (Violentmonkey/Tampermonkey) over an extension for personal use — no store review, trivial to edit, `@match` on `chatgpt.com`. Use an extension only if you need cross-origin fetches or persistent background work.

## Things to watch

- ToS: exporting your own conversations for personal use is normally fine; automating bulk scraping is a different matter. Check current terms.
- Official export: Settings → Data Controls → Export gives you a zip with `conversations.json`. If you just need a one-time archive of everything, use that — it's a supported path and needs no code. A script is worth it mainly for per-thread, on-demand, formatted output.
- Multimodal content: `content.parts` can contain non-string objects (image pointers, audio). Guard with a type check or you'll get `[object Object]` in output.
- Reasoning models emit hidden thought summaries as separate nodes with different content types; decide explicitly whether to include them.

Here's a working reference implementation demonstrating the adapter pattern with API-first, DOM fallback, and validation:

```html





Conversation Exporter — Reference Architecture




  Conversation Exporter — Reference Architecture
  Demonstrates strategy fallback, schema normalization, and validation gating. Uses mock sources so it runs standalone.



  
    
      Simulate source
      Available strategies
      backend-api (JSON tree)
      hydration payload
      DOM scrape
      Uncheck to simulate a strategy breaking. The runner walks the list in order and stops at the first source that passes validation.
    

    
      Options
      Output format
      
      Active branch only
      Front-matter / metadata
      Include reasoning nodes
      Per-message timestamps
    

    
      Pipeline
      
    

    
      
      
    
    
  

  
    
    
      
      
      
      
    
    Press "Run export".
  





```

Try unchecking `backend-api` to watch it degrade to hydration, then to DOM — and note how the DOM path fails validation differently. That's the behavior you want in production: loud, diagnosable failures instead of a truncated file you don't notice until you need it.

**Bottom line:** API-first with DOM fallback, everything funneled through one normalized schema, with validation gating each strategy. That combination survives UI redesigns, which is where naive scrapers die.

what approach is best for making a relaible browser script f...