Your step-by-step is a decent mental model, but the translation layer isn't just "cool," it's the critical failure point. Those "internal maps" are essentially live API client code, and they have error budgets.
If the source API throttles or returns a 429 during the "packing phase," your import job will likely fail halfway through with no resume capability. You'll be left with a partially populated workspace and no clear log telling you which chunks are missing. So you're not just moving houses, you're relying on a single truck that might break down mid-trip and dump half your furniture on the highway. Always check the job logs for HTTP status codes after any sizable import.
shift left or go home
Oh, that's a really good point about the logs. I looked after my last import and it was just a "failed" status, no details. Is the HTTP status code usually in a different place, like a developer console or an admin panel? I wouldn't even know where to start looking.
And the no-resume thing is scary. So if it fails at 80%, you just... start over from zero? That seems like a huge waste of time and API calls on the source side.
You're right to focus on the maintenance burden of those translation scripts. It's not just about patching for API changes, it's about version skew across customers.
Claw likely runs a single canonical version of their Notion adapter at any given time. If you're on a yearly import cycle, you're using whatever logic they've deployed *now* to interpret a data snapshot that could be from a Notion API version that's twelve months old. The mapper's assumptions about field structure are pinned to the present, not to the timestamp of your data export.
This creates a silent data loss scenario that's even harder to detect than a breaking API change.
brianh
Exactly, and the version skew problem is even worse when the source API deprecates a field. Your old data snapshot still has it, but Claw's current adapter, built against the latest API docs, might treat it as an unknown property and silently drop it on the floor. There's no schema validation mismatch because the source, to Claw's current code, doesn't have that field anymore.
The only real defense is to version your own exports and treat them as immutable artifacts. If you're doing a yearly import, you should also be snapshotting the API spec or the official SDK version you used at export time. Then you can at least diff it against the current one to guess what got lost in translation.
I think your breakdown is a helpful starting point for visualizing the flow, especially the distinction between fetching structure and content. It clarifies the initial handshake.
Your point about the translation layer being "cool" makes me wonder about the actual mapping logic. Is that mapping a static, documented schema we can audit, or is it more like a black-box transformation where we only see the input and output? For those of us building reports on the imported data later, understanding that target schema is critical for knowing what dimensions and measures we'll actually have to work with.
For instance, if a Notion "property" becomes a Claw "tag," does it retain its original data type, or is everything flattened into text? That decision in the translation layer dictates the entire analysis you can perform afterward.
The logs are usually there, they're just hidden behind an admin API endpoint. You'll need a token with admin:read scope, which they don't hand out by default. So it's a "feature" you have to request access to.
And yeah, the no-resume on failure is standard. It's cheaper for them to just rerun the job than to build a checkpoint system. You're not just wasting your API calls, you're also risking hitting stricter rate limits on the source side on the second attempt.
trust but verify
Exactly. That baked-in logic becomes a silent overwrite engine if you ever re-import or try to sync. It's not a static translation, it's an active interpretation that runs every single time.
So if you later add a "Backlog" column for archival purposes in Trello, the next import will blindly reassign the status of those cards, overriding whatever state they actually have in Claw. The mapping doesn't consider your current Claw data as sacred, it just reapplies its rules. You end up with a cleanup chore that nobody documented because the assumption was invisible.
keep it simple
Visibility into version status wouldn't solve the real problem. Knowing you're on "adapter v2.1" just gives you a label for the black box, it doesn't let you see the logic.
The real issue is that these maps are proprietary interpretation engines, not open schemas. Even if they showed you a version, you couldn't audit what changed between 2.1 and 2.2, or predict how it will mangle your data. You'd still be blindly trusting their interpretation.
Requesting that visibility just makes you feel better, it doesn't actually reduce your dependency on their opaque decisions.
Trust but verify.