Intentflow Reconcile documentation

What does the "Data coverage" table mean?

Each row is a data type (device inventory, interfaces/IPs, VLANs, LLDP topology), and the fraction is how many of the devices in this batch had that specific data uploaded - not a count of individual files or objects. "Interfaces/IPs: 1/2" means one of the two devices in the batch had a running-config uploaded; the other didn't. A device can be fully identified but still show a gap in another row if that command's output was never uploaded for it.

Missing source data never implies deletion or removal. Not uploading show vlan this round is never read as "this device has no VLANs" - it's read as "nothing to check this round," and no VLAN field is touched. The same holds for every data type: skip the LLDP upload and no cable is ever flagged, skip the running-config and no interface or IP address on that device is touched at all. When interface data is present, IP assignment is treated differently, but this isn't an exception to the rule above - it's the rule applying to a case where the data genuinely is there: an address previously assigned in NetBox but absent from that interface's observed configuration can be proposed for unassignment, scoped strictly to interfaces this same upload actually covers, and only ever as a proposal you explicitly confirm, never a default.

Does "Synchronized" mean everything on the page got written?

A clean "Synchronized" does mean exactly that - every confirmed entity's outcome is final, nothing left to look at. If something's still held - a field you didn't resolve, a Removed IP nobody confirmed, a physical link whose neighbor couldn't be identified - the batch instead shows "Synchronized with issues": the write itself completed with no errors, but there's a decision still waiting on you. If a device actually raised an error while being written, the batch shows "Failed", and any other confirmed device in the same batch still got its own full, independent attempt - a "Failed" batch can still have most of its devices synchronized cleanly. Open the batch and check the synchronization log for the precise, per-entity record of what actually happened either way.

What's in the synchronization log?

One line per device, interface, VLAN, VRF, Prefix, IP address, Site, Role, and cable the synchronization step touched, with its outcome - Created, Updated, Unassigned, Kept, Unresolved, or Failed (see Reconciliation & synchronization states). It's built from what actually happened during the write, not from what was merely proposed at parse time - the two can differ if something changed in NetBox between review and synchronize, since synchronizing always re-checks live NetBox first rather than trusting a stale plan.

How is a field classified as safe vs. conflicting?

Every field Intentflow could write is compared three ways: the new value from this import, the live value in NetBox, and the value Intentflow last synced there. In order:

That "last synced" value isn't kept in some separate database - it's stored directly on the object itself, in a hidden intentflow_sync custom field created during setup, and it only ever holds what Intentflow itself last wrote. It also moves forward every time a field applies cleanly, so a manual edit only shows up as a conflict if it happened after Intentflow's most recent import touched that field - an edit from three imports ago that's already been synced over won't reappear as a conflict now.

A field that's never been synced and differs is held, not silently written - a NetBox that already had devices, interfaces, or VRFs before you ever ran an import is the normal case here, not an edge case, and there's no way to tell "this predates Import" from "this import's value is stale" without a sync history. Needs Review and Conflict resolve exactly the same way - keep NetBox's current value, or use the imported one - the difference is only in why the field is held, shown next to each one on the review screen. A field that already matches, with no sync history yet, needs no decision at all: it silently gets a baseline the next time anything else on that same object is written, so it's protected against actually going stale later without ever showing up as a false alarm now.

What's checked, at the device and interface level?

Devices: name. Interfaces: description, admin state, and (once VLAN data is present for that device) trunk/access mode and VLAN assignment - checked in both directions, so an interface that lost its VLAN assignment since the last import is caught the same way as one that gained or changed one. That check only ever runs when this round's upload actually included VLAN data for that device - see the missing-data principle above; a batch with no VLAN command uploaded leaves every interface's VLAN fields untouched, never reads the absence as "clear everything." A single interface can have one field land as a safe update and another as a conflict at the same time - resolving the conflict never blocks the unrelated safe field from applying.

How do I resolve a conflict?

Each conflicting field on the review screen gets a choice: keep NetBox's current value, or use the imported value. It defaults to keeping NetBox's value - nothing changes unless you explicitly pick otherwise. Choosing "use imported value" is itself the confirmation to apply it; there's no separate checkbox to remember on top of that choice.

What about VLANs and physical links specifically?

VLANs are created if they don't already exist, matched by Site and VLAN ID if they do - and if one does already exist, its name is re-checked for drift the same way a device or interface field is: a safe rename (nothing's touched it since our last import) applies automatically, a genuine conflict (renamed in NetBox independently) gets its own "VLAN conflicts" section on the review screen. Physical links work the same way: a link is created if neither end already has a cable, left alone as already-correct if one end is already cabled to exactly the expected neighbor, and surfaced under "Physical link conflicts" if an end is cabled to someone else - pick "use imported value" and the old cable is disconnected and the new one created, or leave it on NetBox's current connection to skip it this round. Resolving a physical-link conflict is the one place Import can delete anything at all - a narrow, Cable-only exception to the "never deletes" rule, needed because NetBox won't let an already-cabled port take a second cable.

What about VRFs and Prefixes?

Prefixes are New-or-In-Sync only, matched by identity alone (VRF + the CIDR itself, independent of Site) - a derived Prefix carries no imported description or status to compare against an existing one, so there's genuinely nothing to conflict on. VRFs get the fuller treatment: matched by name, and if a route-distinguisher and/or description were parsed for it (Cisco/Arista pull both from the VRF's own config block; Junos gets a route-distinguisher only, from the same show route instance detail upload used for membership - that platform's source command has no description field at all, so Junos never proposes touching one either way), those are re-checked for drift the same way a VLAN's name is - a safe change applies automatically, a genuine conflict gets its own "VRF conflicts" section on the review screen.

What about IP addresses?

An address that doesn't exist in NetBox yet is New. One that already exists and is assigned to exactly the device and interface this import expects is In Sync. One that already exists but is assigned to a different device or interface - or isn't assigned to anything at all - is a conflict: reassigning an address is a meaningful write (it could disrupt whatever's actually using it right now), so it's held under its own "IP address conflicts" section on the review screen with the same keep-NetBox's-value-or-use-imported choice as everything else, never silently moved.

An address NetBox has assigned to an interface this upload covers, that the upload no longer lists there, shows up separately as Removed, under its own "IP addresses no longer in this config" section. Scoped strictly to interfaces this same upload actually has data for - an interface the upload doesn't mention at all tells us nothing about its addresses, so nothing is claimed about it (see the missing-data principle above). The default is to leave it assigned; opting in unassigns it - detaches the address from the interface, the record itself, its VRF, and its history all stay in NetBox, nothing is deleted. This is never automatic, including through POST /api/reconcile/import/{batch_id}/synchronize's safe-subset path - it always requires the same explicit, per-address confirmation a reassignment conflict does.

How do I connect my own NetBox?

From your dashboard, enter your NetBox's base URL and an API token you generate in NetBox itself. That's the whole setup - there's nothing to install, no agent, and no inbound access to your network. Intentflow calls your NetBox's REST API the same way any other API client would. If your NetBox isn't reachable from the internet, it won't be reachable from Intentflow either; that's the one hard requirement.

Which NetBox versions are supported?

Reconciliation - reading your NetBox and showing you every difference - works across the compatible range. Synchronization is deliberately narrower, because writing into an object model we haven't tested against is how you get confidently wrong results rather than an obvious error. Your connected version is checked automatically and your dashboard always shows which row you're in.

What permissions does the API token need?

At minimum, read access to devices, interfaces and IP addresses - without all three, a reconciliation report would silently look like an empty NetBox rather than a permissions problem, so Intentflow refuses the connection instead of showing you that. Read access alone is a perfectly good place to start: you get the full discovery and reconciliation report, and synchronization is simply unavailable until you widen the token. To synchronize, it additionally needs write access to the object types you want written. It also needs permission to manage custom fields, unless the one field Intentflow uses is already present in your NetBox - in which case a token that can't manage custom fields is fine, and Reconcile detects that rather than assuming the worst.

Does connecting my NetBox change anything in it?

No. The connection check is strictly read-only - it reads your version, what the token can see, and which optional models exist. It creates nothing, and we hold ourselves to that in the test suite rather than as a promise.

Synchronizing does make exactly one schema addition, the first time you run it: a custom field named intentflow_sync, which records which fields Intentflow itself last wrote and when. That field is what makes the three-way comparison possible - it's how Reconcile can tell "you changed this by hand" apart from "this drifted since our last sync" and refuse to overwrite the former. Nothing else in your schema is touched, and no object is ever written until you confirm it.

What if I don't run the netbox_bgp plugin?

BGP sessions are still parsed from your configs, still counted in Discovery, and still appear in your reports - they just aren't compared against NetBox or synchronized, because there's nowhere in your NetBox to compare them against. Reconcile says so explicitly on the batch rather than quietly leaving them out: the objects are real and we found them, it's their representation in the target NetBox that's unavailable. Everything else reconciles normally. Installing the plugin later needs no action here - the next import picks it up.

What happens if I revoke or narrow the token later?

Reconcile re-checks what your NetBox can do before every import, so a token you widen (or a plugin you install, or a NetBox you upgrade) takes effect on the next run with nothing to re-enter. If a token is revoked partway through a synchronization, Reconcile stops rather than retrying every remaining object against a credential that will refuse all of them, and the report records exactly what was written before it stopped. Re-running after fixing the token is always safe.

Can I point Reconcile at a different NetBox?

Yes, but not repeatedly: a subscription covers one network, so it may be repointed at a genuinely different NetBox deployment once per month. That is what a migration needs; it is not enough to service several customers' NetBoxes in turn from one subscription. If a migration goes wrong and you need to switch back sooner, contact us and we will lift it.

Routine changes to the same NetBox do not count and are unlimited: rotating or replacing the API token, changing authentication or TLS settings, or correcting the URL you entered. Switching from http to https, adding or removing a trailing slash or an /api suffix, changing the case, or naming the default port explicitly are all recognised as the same deployment.

When you do switch, existing reconciliation history stays attached to the NetBox that produced it - the drift baseline a past report was measured against lives inside that instance, so trend comparisons do not cross the boundary.

Is automated (CI-triggered) import available on every plan?

Manual upload from the dashboard is free on every plan, Free through Enterprise. Triggering imports from CI - the POST /api/reconcile/import path below - is available on Business, Enterprise and Reconcile, since it's meant for recurring, unattended use rather than a one-off upload. Standalone Reconcile is included because keeping your own NetBox current between manual uploads is the point of it. Free-tier accounts don't see the "Generate API key" option.

Is there a limit on how many imports I can run?

A standalone Reconcile subscription includes 30 reconciliation runs a month. One run covers the whole cycle for a single upload - discovery, reconciliation, your review, and synchronizing the changes you approve - so reviewing a report, re-running the reconciliation on it, or syncing it later never costs a second run. An upload we could not read anything from is not counted at all.

The allowance resets monthly from the date Reconcile was activated on your account, which is not necessarily your billing date, so an annual subscription gets the same 30 runs each month. Worth planning for if you import from CI: a nightly job is about 30 runs a month on its own, so if you also import on every merge, tell us and we will sort out the capacity.

Imports on a Hosted NetBox plan are not metered - Reconcile is a bundled feature of those plans rather than the product being bought.

Does a CI-triggered import write anything on its own?

No - uploading, whether from the dashboard or from POST /api/reconcile/import, only ever parses and reconciles. Nothing is written to NetBox until something explicitly synchronizes it. For a manual upload that's a person clicking "Sync selected changes" after reading the report; for a CI-triggered one, it's a second, deliberate call to POST /api/reconcile/import/{batch_id}/synchronize, which writes the safe subset - no-ops, safe updates, and new devices whose Site match came from your own IPAM data specifically (the one signal backed by curated data, not a guess). Anything uncertain - any conflict, any weaker-signal new device - is left for a human to resolve on the normal review screen whenever they check in.

How does the API key work?

Generated from the Import page, shown once in plaintext, never again - only its hash is stored, the same disclosure model as a GitHub personal access token. It authenticates every /api/reconcile/import... endpoint below (see API reference) - nothing else in the app. Generating a new key immediately invalidates the old one; there's no window where both work.

What does a CI job actually look like?

Point a scheduled job - a nightly GitHub Actions run, a cron on your backup box, whatever already collects your config dumps - at POST /api/reconcile/import with the API key as a bearer token and the archive as the request body. You get a batch_id back immediately; poll GET /api/reconcile/import/{batch_id} until status leaves parsing. Once it's reconciled, that same response already tells you reconciliation.new/changed/in_sync - call GET /api/reconcile/import/{batch_id}/report if you want the actual per-entity Imported-vs-NetBox detail behind those counts, not just the totals. Then decide what to do: call POST /api/reconcile/import/{batch_id}/synchronize to write the safe subset, fail the build if devices_needing_review is non-zero, post the diff to Slack, or just let it sit until someone opens the dashboard. Intentflow doesn't impose an opinion there. Full request/response shapes for every step are in the API reference below.