# Blueprintr Docs: full content

> Every public documentation page from Blueprintr Docs as raw markdown.

---

# Continuum Integrations: Overview
URL: https://docs.blueprintr.io/foliums/continuum-integrations

> What each Continuum product connects to, which licence it needs, and where its credentials sit.

Continuum connects a diagram or a stratum to the systems it describes, so the drawing can be regenerated and the detail on it comes from the source.

Continuum Cloud, Continuum Link and Continuum Local are licensed separately and do different things.

| | Continuum Cloud | Continuum Link | Continuum Local |
| --- | --- | --- | --- |
| Connects to | AWS and Azure | 29 monitoring, ITSM, on-call, uptime and source control platforms | 10 on-premise monitoring, IP address management and backup systems |
| Puts data on strata | Yes | Yes | Yes |
| Draws on a canvas | Yes | No | No |
| Licence | Teams | Enterprise | Enterprise |
| Permission | `cloud_connections.manage` | `continuum_integrations.manage` | `continuum_integrations.manage` |
| Where credentials sit | A read-only role in your own account | Encrypted by Blueprintr | On your own agent. Blueprintr never stores them |

Continuum Local is the on-premise half of Continuum Link rather than a product of its own. It shares Link's gate and its connectors.

## Choosing one

Generate a diagram from an AWS account or Azure subscription with [Continuum Cloud](/foliums/continuum-integrations/continuum-cloud).

Put live operational data beside something already drawn with [Continuum Link](/foliums/continuum-integrations/continuum-link).

Reach an on-premise system that cannot be called from the internet, or keep its credentials inside your network, with [Continuum Local](/foliums/continuum-integrations/continuum-local).

## What Continuum does not do

> [!IMPORTANT]
> Continuum Link never writes to a canvas. Only Continuum Cloud draws.

Scheduled polling is unavailable on every plan. Continuum Cloud syncs when you ask it to, and a Continuum Link tab refreshes when an editor presses refresh. Nothing updates on a timer.

Blueprintr evaluates no conditions, holds no thresholds and pages nobody. It reads state from the systems that do.

## Before you publish

Both products write into strata, and a stratum follows the blueprint's own visibility. On a public blueprint, that means anonymous readers.

Continuum Cloud strata carry account ids, resource ids, regions, addresses and a raw payload. Continuum Link panels are reader-visible for every connector except Datadog, LogicMonitor, Auvik, Rootly, ServiceNow, GitHub and NetBox, which default new connections to blueprint editors, and Infoblox and Veeam Backup & Replication, whose panels are always for editors only.

Review what a diagram carries before publishing it publicly. Changing an audience later applies to subsequent refreshes and cannot recall copies already shared.

---

# Continuum Integrations: Continuum Cloud
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-cloud

> Reading an AWS account or Azure subscription read-only, and drawing what is there onto a Vellum canvas.

Continuum Cloud reads an AWS account or Azure subscription and draws what it finds onto a Vellum canvas, with each resource's detail attached as a stratum.

It needs a Teams licence and `cloud_connections.manage` on the organisation or team that owns the connection. Free and Premium have no Continuum surface, and creating a connection below Teams refuses with "Continuum is a Teams-plan feature."

## What it produces

One Continuum tab in a blueprint, backed by a private Vellum document named after the tab.

| Artefact | What it holds |
| --- | --- |
| Shapes on a canvas | Resources the layout draws, nested inside the boundaries in the source: accounts, regions, VPCs and subnets, resource groups |
| A stratum per resource | Identity, configuration, per-type tables, tags, related strata, and the raw payload in a collapsed `Raw data` disclosure |
| A poll run per scope, per sync | What was found, what changed, and every read that failed |

> [!IMPORTANT]
> A stratum is a blueprint file, so it follows the blueprint's own visibility. On a public blueprint, anonymous readers see every discovered resource's account id, resource id, region, addresses and the `Raw data` payload. Review what a Continuum diagram carries before publishing it publicly.

Resources that describe relationships rather than occupy space, such as route tables, security groups, network ACLs, IAM and KMS, get a stratum with no shape. They are filed under a `(Context)` folder in the Files sidebar and cross-linked from the resources they affect.

A resource collapsed into a group shape, such as Auto Scaling members or a Lambda name family, also gets a stratum with no shape of its own. Those sit alongside the drawn resources rather than under `(Context)`.

## What is discovered

Continuum discovers 77 AWS resource types and 75 Azure resource types. Of those, 53 AWS types and 52 Azure types are drawn as shapes by default. The rest are read for their relationships, for the containers they define, or for stratum context.

> [!NOTE]
> A scope narrows by place and by tag, never by service. There is no resource-type picker.

## Permissions

Every action on the settings page checks `cloud_connections.manage` on the owning organisation or team. Built-in owners and admins hold it; anyone else needs it granted through a custom role.

`integration.manage` is a different permission, for embedding Blueprintr content in SharePoint and Confluence. Holding it opens the settings page but grants nothing in Continuum.

## Limits

| | Team | Enterprise |
| --- | ---: | ---: |
| Cloud connections per owner | 3 | Unlimited |
| Scopes per diagram | 3 | Unlimited |

`Team settings → Plan & limits` also shows **Resources per integration** as 200 on Teams. Nothing enforces that figure today, and a sync is not truncated at 200 resources.

## Syncing is manual

Open the tab's settings cog and choose `Sync now` to re-discover every scope, or `Re-sync` one scope from `Settings…`.

> [!IMPORTANT]
> Scheduled syncing does not work on any plan. The `Auto-sync` picker offers Off, Every 1h, 4h, 12h and 24h, but choosing any cadence returns "Scheduled polling is not available yet - Continuum runs one-time scans." That is not a plan gate and no upgrade lifts it.

## Views on the same canvas

The canvas carries a `View` switcher. Base topology is the default; the others recolour the same shapes to answer one question each: Routing, Security groups, Cost (est.), IP addresses, Public exposure, Availability zone and Tag coverage. Views authored on the diagram appear in the same list.

## Setting one up

[Connecting an AWS account](/foliums/continuum-integrations/continuum-cloud/connecting-an-aws-account) covers the role, the verify step and the first scan.

[Connecting Azure](/foliums/continuum-integrations/continuum-cloud/connecting-azure) covers the app registration and the Reader grant.

[Scopes and syncing](/foliums/continuum-integrations/continuum-cloud/scopes-and-syncing) covers what a diagram covers and how to keep it current.

[Keeping diagrams true](/foliums/continuum-integrations/continuum-cloud/keeping-diagrams-true) covers what a sync preserves and what the shape outlines mean.

---

# Continuum Integrations: Connecting an AWS account
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-cloud/connecting-an-aws-account

> Creating the read-only role, verifying the connection, and scoping the first sync.

Connecting an AWS account takes four steps: create the connection, create a read-only role in AWS, verify it, then scope a diagram.

You need a Teams licence and `cloud_connections.manage` on the owning organisation or team. Below Teams the action refuses with "Continuum is a Teams-plan feature."

> [!IMPORTANT]
> Set the connection scope correctly at the start. `Single account` and `AWS Organization` stay changeable only while the connection is a draft, by going Back in the wizard. Once a role has been recorded the choice is fixed: "This connection already has a role, so its scope can't be changed. Create a new connection instead."

> [!STEPS]
>
> === Create the connection
>
> Open `Settings → Continuum` on the organisation or team, select the AWS card, then choose `New connection`. Enter the 12-digit `AWS account number`, choose `Single account` or `AWS Organization`, pick the region to discover, and give it a display name.
>
> Single account creates one read-only role in one account. AWS Organization creates a management role that enumerates the organisation plus a StackSet member role in every account, including accounts created later.
>
> === Create the role in AWS
>
> The connection page shows the stack name, the role name and the external ID. Choose `Launch with CloudFormation` to open the AWS console with those values filled in. To deploy it yourself instead, open `Or do it manually - AWS console or CLI` for the same template and parameters.
>
> An AWS Organization connection uses the org StackSet template, launched from the management or delegated-admin account. It needs trusted access between AWS Organizations and CloudFormation StackSets, enabled once per organisation.
>
> === Verify
>
> Blueprintr watches the account and picks the role up on its own once the stack finishes. To finish immediately, paste the role ARN into `Or paste the role ARN` and choose `Verify`. The header changes to `Verified` and the page reports that the role assumed and responded.
>
> === Scope a diagram
>
> In the blueprint, open the `+` menu in the tab bar and choose `Continuum`. Select the connection, name the tab, confirm the account and regions, then choose `Create`. Narrow it first with `Refine VPCs / subnets` or a tag filter.

Regions are fixed when you create the connection: one region in single-account mode, a set of regions in AWS Organization mode. There is no region control on the connection afterwards, so covering a new region means a new connection.

## What the role can do

The template grants list and describe actions. Nothing in it changes infrastructure, and Continuum never writes to your cloud account. The external ID stops another Blueprintr tenant assuming your role, so do not omit it. On the current template it is filled in for you.

Reading Terraform state is not included. Adding a state backend to this connection also needs `s3:GetObject` on the state object added to the role policy.

## If a sync will not start

An `AWS Organization` connection needs the org StackSet role. Pointing one at a single-account role fails to load the account list, because the single-account template grants no `organizations:` permissions. Create a `Single account` connection instead, or deploy the StackSet.

A finished sync reports what it could not read, under `Adapter errors`. Read that list before concluding a resource was decommissioned.

Reaching the connection cap refuses with "Connection cap reached (3 per org)", or "(3 per team)". Blueprintr first reclaims your own drafts that have sat untouched for a day with no credential and nothing referencing them; drafts from the last 24 hours, and anyone else's, are left alone.

## Next

[Scopes and syncing](/foliums/continuum-integrations/continuum-cloud/scopes-and-syncing) covers what a diagram covers and how to keep it current.

---

# Continuum Integrations: Connecting Azure
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-cloud/connecting-azure

> Registering an Entra application, granting it Reader, and verifying the connection.

An Azure connection covers a set of subscriptions through one Entra application granted read-only access.

You need a Teams licence and `cloud_connections.manage` on the owning organisation or team.

> [!STEPS]
>
> === Register an application
>
> In Entra, register an application and create a client secret on it. Azure shows the secret value once.
>
> === Grant Reader
>
> Assign the built-in **Reader** role to that application at subscription scope, on every subscription you want visible. Where policy forbids built-in Reader, the wizard offers a narrower custom role definition to create instead.
>
> === Enter the three values
>
> Open `Settings → Continuum`, choose `New connection`, then Azure. Enter the **Directory (tenant) ID**, the **Application (client) ID** and the **Client secret value**. The secret value, not the secret id.
>
> === Verify
>
> Blueprintr authenticates, lists the subscriptions the application can see, and reads one resource group.

The **Federation** tile beside **Client secret** is marked roadmap and cannot be selected yet, so the client-secret path is the only one available.

## Secret lifetime

You create the secret in Azure, so Azure decides how long it lives. The copy-and-run script the wizard offers creates it with a two-year life. The portal click-path leaves Azure's own default, so check it before relying on the connection.

Blueprintr encrypts the secret at rest and never returns it to the browser. Replace it later from the connection's detail page rather than by rebuilding the connection.

## If verification fails

A connection whose application has no Reader grant fails outright: "The connection authenticated but no subscriptions are visible to it. Assign the Reader role at subscription scope." Grant Reader, then verify again.

Discovery only runs on a connection that has verified, so verify after any credential change.

## Terraform state

A Terraform backend can be set on an Azure connection's detail page, but drift reconciliation works on AWS connections only. The form is not provider-gated, so an Azure connection accepts a backend and returns nothing from it.

## Next

[Scopes and syncing](/foliums/continuum-integrations/continuum-cloud/scopes-and-syncing) covers choosing subscriptions and locations, and running the first sync.

---

# Continuum Integrations: Scopes and syncing
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-cloud/scopes-and-syncing

> Choosing what a Continuum diagram covers, and running the sync that builds it.

A **scope** is what one Continuum diagram covers. On AWS it is one account paired with one region. On Azure it is one subscription paired with one location.

A diagram can carry several, but they must all come from the same provider. Adding an Azure scope to an AWS tab is refused: "This Continuum tab was created from a different cloud provider. Add the scope to its own Continuum tab instead."

## Choosing scopes

Pick accounts or subscriptions, then regions. Every combination becomes its own scope, so three accounts and two regions is six scopes. The picker shows the running total.

Two optional narrowings apply on top:

| Control | Provider | Default |
| --- | --- | --- |
| `Refine VPCs / subnets` | AWS | Every VPC in the scope |
| `Refine resource groups` | Azure | The whole subscription |
| `Tag filter` | Both | No filter |

A resource is imported when every tag listed matches. The filter applies to all selected scopes.

> [!IMPORTANT]
> The tag filter fails open. A resource whose payload carries no tag data is imported anyway, so untagged resources, and resources whose list API returns no tags at all such as route tables and log groups, still appear. EC2 instances are the exception, because AWS filters them server-side, so an untagged instance is dropped. Do not use the tag filter to keep anything out of a shared diagram.

> [!NOTE]
> There is no resource-type picker. Continuum discovers the types it supports and you narrow by place and by tag, not by service.

> [!TIP]
> Scope to the thing you are explaining, not to the account. An unscoped account produces a diagram of everything in it, which nobody can read.

One commit fans out to at most 12 scopes on AWS and 4 on Azure, and the picker says so when you go over.

On Teams the plan cap of three scopes per diagram bites first, and the picker does not know your plan. A selection of four or more still shows as valid and the server refuses it after you press create. Narrow the selection, or add the rest as extra scopes afterwards.

## Adding, re-syncing and removing scopes

Open the Continuum tab's settings cog and choose `Settings…`. Each scope has `Re-sync`, and `+ Add another scope` adds more.

Every control here needs edit access on the blueprint plus `cloud_connections.manage` on each scope's connection. Without the permission the buttons do not appear.

> [!IMPORTANT]
> `Remove` drops that scope's resources from the diagram and deletes the strata attached to them. Other scopes are untouched, and the deletion cannot be undone. The confirmation dialog says so.

`Remove` is disabled on the last remaining scope: "Cannot remove the last scope. Delete the Continuum tab instead."

## Syncing is manual

`Sync now` from the cog re-discovers every scope and reports the result, for example "Synced, +3 added, 1 changed, 0 missing."

> [!IMPORTANT]
> Scheduled syncing does not work on any plan. The `Auto-sync` picker offers Off, Every 1h, 4h, 12h and 24h, but choosing any cadence returns "Scheduled polling is not available yet - Continuum runs one-time scans." That is not a plan gate and no upgrade lifts it. Turning it Off is always accepted.

## Reading a sync

Each scope's discovery is recorded as its own **Poll run**, reachable from the history list in `Settings…`, so one `Sync now` across three scopes produces three runs. Removing a scope writes one too.

A run reports what it found, what changed since the last one, and an `Adapter errors` section listing every read that failed.

Check that section before concluding something was decommissioned. A permission error produces a smaller diagram with an explanation, not a silent gap. Once the permission is fixed, choose `Sync now` again.

The ten most recent runs are listed. There is no view that compares two runs side by side.

---

# Continuum Integrations: Keeping diagrams true
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-cloud/keeping-diagrams-true

> What a sync preserves, what the shape outlines mean, and how new resources reach the diagram.

Once a scope has been discovered, Continuum puts the results on a canvas and mints a stratum for every resource it found.

## Shapes and strata

Resources the layout draws become shapes, nested inside the boundaries that exist in the source: accounts, regions, VPCs and subnets, resource groups.

Resources that describe relationships rather than occupy space get a stratum with no shape. Route tables, security groups, network ACLs, IAM and KMS are filed under a `(Context)` folder in the Files sidebar and cross-linked from the resources they affect.

A resource collapsed into a group shape, such as Auto Scaling members or a Lambda name family, also gets a stratum with no shape of its own. Those sit alongside the drawn resources rather than under `(Context)`.

A Continuum stratum's body tab is labelled `Continuum` rather than Overview. It holds a Resource table, a Details table, per-type tables, Tags, links to related strata, and the full payload in a collapsed `Raw data` disclosure. A Terraform drift tab joins it where state is reconciled.

## What a sync preserves

> [!IMPORTANT]
> After the first draw, the canvas you saved is the authority on geometry. Your positions, sizes, labels, styling, groups, notes and connector routes are kept. Only new shapes are laid out.

Containers can grow to make room for additions without moving what is already inside them. Where a container is boxed in by authored content, Continuum places the addition in free canvas space and keeps its resource membership rather than moving your work.

A label or membership you have not customised follows the source. Anything you overrode wins. Managed shapes you deleted stay deleted once the diagram has recorded a refresh baseline. Older diagrams without that baseline preserve customisations conservatively, because a deletion made before the baseline cannot always be inferred.

## New resources wait for you

A resource discovered after the first sync is not added to the diagram straight away. It is drawn on the notes layer with a green outline, and the settings cog's menu shows a running delta such as "+3 new".

Choose `Promote N new resources` from the cog to move them onto the blueprint layer. Until then they sit alongside the diagram rather than in it.

## What the outlines mean

| Outline | Meaning |
| --- | --- |
| Default | Active |
| Red | The source reports the resource offline |
| Dashed grey | Pending removal |
| Red solid, on the notes layer | Removal confirmed |
| Red dashed, on the notes layer | Referenced from outside the scopes you sync, labelled "out of scope" |
| Yellow dashed, on the notes layer | In Terraform state but not found in the cloud, labelled "in tf, not in aws" |
| Green, on the notes layer | Newly discovered, awaiting promotion |
| Amber | Live configuration has drifted from Terraform state |

Drift takes precedence over lifecycle. These outlines come from cloud discovery only. A linked monitoring platform never changes a shape.

## Changing the reading direction

Reading direction is not a control on the tab. Ask the AI assistant to reorder the diagram top down or left to right. It proposes the change and applies it only after you confirm.

> [!IMPORTANT]
> Confirming lays out every managed shape again and discards the positions you moved them to. It is the one action on this page that does. Ordinary syncing, additions and promotion all preserve your layout.

## Version restore is refused

Once a blueprint carries Continuum-managed content, restoring an older version of it is refused. A version snapshot never captured the connections and bindings behind those tabs and strata, so a restore would delete them with nothing to rebuild from. Remove the Continuum component and unbind those strata first.

## Binding one shape instead

A shape you drew yourself can be tied to a single live resource. Add a stratum to it, open `+ Add tab` and choose `Continuum`, then pick a connection, a region or location, and one resource. `Pull now` re-reads it.

AWS and Azure connections can both be bound. A Terraform-state connection cannot: "Only AWS and Azure connections can back a live stratum."

The control appears only for a signed-in editor on a Teams plan or above, on a rich stratum in a saved blueprint. Binding also needs `cloud_connections.manage` on the organisation or team that owns the connection; without it the picker reports no usable connections. Readers never see it.

---

# Continuum Integrations: Continuum Link
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link

> Attaching a dated snapshot from a monitoring, ITSM or on-call platform to the stratum that explains it.

Continuum Link attaches a saved snapshot from an operational platform to a stratum, as its own read-only tab. Alert state, service ownership and change context sit beside the thing on the diagram they refer to.

It needs an Enterprise licence, edit access to the blueprint, and `continuum_integrations.manage` on the organisation or team that owns the connection. Below Enterprise the engine refuses with "Continuum integrations are an Enterprise feature." This is a separate gate from the Teams licence Continuum Cloud uses; holding one does not grant the other.

> [!IMPORTANT]
> Continuum Link never draws on a canvas. It cannot add, move, recolour or delete anything on a diagram. To generate a diagram from infrastructure, use [Continuum Cloud](/foliums/continuum-integrations/continuum-cloud).

## Connect a platform

Open `Settings → Continuum` on the organisation or team, find `Operational integrations`, and choose `New integration`. The form asks for a `Type`, a `Name`, whatever non-secret fields that connector declares, and one credential. Choosing `Connect & verify` stores the credential and runs a handshake against the platform in one step.

Jira Cloud and Jira Service Management Operations replace that button with `Connect with Atlassian` and sign you in instead. Most other connectors take a pasted token or key, GitHub and GitLab included.

Two groups store no credential here. AWS CloudWatch reuses a verified AWS cloud connection: pick that connection and a region, and widen that connection's role with the CloudWatch and Logs actions the form lists. The ten on-premise connectors keep their credential on the [Continuum Local](/foliums/continuum-integrations/continuum-local) agent, and Blueprintr never stores it.

Credentials are encrypted at rest, are never returned to the browser, and are never written into a snapshot. To replace one, enter the new value; there is no way to read the old one back.

## Link an object to a stratum

Save the blueprint, open a stratum, and choose `Continuum Link` from its `+ Add tab` menu. Search across every verified connection you can use, review the candidate's identity, then choose `Link object`. The first snapshot is fetched before the binding is saved, so a link that would have failed never lands.

One connection holds one linked object per stratum. Selecting a different object from the same connection replaces that connection's binding. A stratum can carry 20 linked tabs; a twenty-first is refused with "This stratum already has the maximum of 20 integration tabs."

Two aids propose candidates instead of you searching. `Suggest integrations…` on a shape's right-click menu scores matches from that shape's own identifiers. `Scan for integrations` does the same across a whole blueprint, reading titles, tab bodies, file content and diagram shape labels, up to 200 identifiers per scan. Neither writes anything: Scan attaches only what you tick and apply.

## Refreshing is manual

Opening a tab shows its saved snapshot and contacts nothing. Nothing polls, and no schedule exists.

Each linked row has two icon buttons with no visible text. The circular-arrows icon re-fetches, and its tooltip reads "Re-fetch this integration's data". The broken-link icon removes the tab, with the tooltip "Remove this integration tab", and asks you to confirm.

A banner above every saved tab states which of these applies:

| Banner | Meaning |
| --- | --- |
| Saved snapshot | The last fetch succeeded and is still considered fresh |
| Snapshot needs a refresh | Older than the connector's freshness window |
| Incomplete snapshot | Some sections could not be read; counts are lower bounds |
| Last refresh failed | The previous snapshot is still shown, unchanged |
| Refresh paused | The connection is suspended |

Only nine connectors declare a freshness window: PagerDuty, incident.io, Rootly, Datadog, LogicMonitor, Auvik, Jira Cloud, Jira Service Management Operations and ServiceNow. Most set five minutes. Jira Cloud work items set fifteen, Jira Service Management on-call coverage sets two, and ServiceNow sets one day.

> [!IMPORTANT]
> The other nineteen connectors never report a snapshot as needing a refresh. A months-old Grafana or GitHub tab still reads "Saved snapshot". Check the fetch time on the tab rather than trusting the banner.

A failed read never becomes a healthy-looking zero. Missing sections are marked unavailable or partial, and a failed refresh keeps the previous snapshot.

## Who can read a saved panel

This depends on the connector, so check it before linking.

| Connector | Default audience for a new connection |
| --- | --- |
| Datadog, LogicMonitor, Auvik, Rootly, ServiceNow, GitHub, NetBox | Blueprint editors only |
| Infoblox, Veeam Backup & Replication | Blueprint editors only, with no setting to widen it |
| Every other connector | Everyone who can read the stratum |

A connector in the last row has no audience setting, so its panel reaches every reader of the blueprint. On a public blueprint that includes anonymous readers, embeds and exports. The seven connectors in the first row offer a reader-visible option, labelled `All Blueprint readers`.

> [!IMPORTANT]
> A connection created before those settings existed keeps its historical behaviour, which is reader-visible and detailed, until an administrator opens `Configure` and saves. Check old connections rather than assuming the newer defaults apply.

An audience change applies to later fetches. It does not rewrite snapshots already saved, and it cannot recall versions, templates, exports, embeds or AI answers that already carry the data. Unlinking a tab and revoking a credential cannot recall them either.

## Managing a connection

| Control | What it does |
| --- | --- |
| `Configure` | Edits the connection's non-secret settings, including audience and detail |
| `Verify` | Re-runs the handshake, including optional capabilities |
| `Suspend` and `Resume` | Stops and restarts search and refresh. Saved snapshots stay readable |
| `Rotate token` or `Replace credentials` | Reveals a field, then `Verify & replace` swaps the credential only if the new one verifies |
| `Remove token…` | Clears the stored credential and suspends the connection |

Deleting a connection is refused while tabs are still bound to it: "This integration has N stratum tab(s) bound to it. Remove those first."

If the plan lapses, the section stays open in a cleanup-only mode: suspending, inspecting, unlinking and disconnecting still work. Adding or refreshing data needs Enterprise again.

## Which platforms

39 connectors are registered. 29 work directly, and 10 more need [Continuum Local](/foliums/continuum-integrations/continuum-local) for systems Blueprintr cannot reach.

The [connector reference](/foliums/continuum-integrations/continuum-link/connector-reference) lists all of them with what each one asks for and shows. Eight have a guide of their own:

> [!TILES 3]
>
> === [PagerDuty](/foliums/continuum-integrations/continuum-link/pagerduty)
>
> Service ownership, incident state and on-call coverage.
>
> === [incident.io](/foliums/continuum-integrations/continuum-link/incident-io)
>
> Catalog services and the incidents attached to them.
>
> === [Rootly](/foliums/continuum-integrations/continuum-link/rootly)
>
> Incident response and follow-up progress.
>
> === [Jira](/foliums/continuum-integrations/continuum-link/jira)
>
> Work items, and alerting from Service Management Operations.
>
> === [Datadog](/foliums/continuum-integrations/continuum-link/datadog)
>
> Hosts, monitors, catalog services and reliability objectives.
>
> === [LogicMonitor](/foliums/continuum-integrations/continuum-link/logicmonitor)
>
> Devices, DataSource instances and resource groups.
>
> === [Auvik](/foliums/continuum-integrations/continuum-link/auvik)
>
> Network device context and recent alert history.
>
> === [ServiceNow CMDB](/foliums/continuum-integrations/continuum-link/servicenow-cmdb)
>
> The configuration item, its relationships and its open work.

---

# Continuum Integrations: Connector reference
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/connector-reference

> Every Continuum Link connector, what it asks for when you connect it, and what its saved panel shows.

39 connectors are registered. 29 connect directly and 10 need [Continuum Local](/foliums/continuum-integrations/continuum-local). All of them need an Enterprise licence and `continuum_integrations.manage`, and none of them draws on a canvas.

Every connector can be found by free-text search when linking a stratum. Where a credential field has no label of its own, the form calls it `API token`.

## Alerting and on-call

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [PagerDuty](/foliums/continuum-integrations/continuum-link/pagerduty) | API token | PagerDuty region, Imported content | Service identity, open incidents, incident coverage, ownership, on-call coverage, related services |
| [incident.io](/foliums/continuum-integrations/continuum-link/incident-io) | API key | Catalog types, relationship fields, attributes, history days, remediation counts | Catalog entry and related incidents, or one incident with durations and follow-ups |
| [Rootly](/foliums/continuum-integrations/continuum-link/rootly) | API key | Content audience, ownership context, on-call coverage, action item counts | Service response and history, or one incident's lifecycle |
| [Jira Service Management Operations](/foliums/continuum-integrations/continuum-link/jira) | Atlassian sign-in | Site, counts-only | Alert scope with open, unacknowledged and snoozed counts, or an on-call schedule |
| FireHydrant | API key | None | Service tier and active incidents, or one incident |
| Splunk On-Call | API credentials (JSON) | None | One incident, paged teams and state transitions |
| xMatters | Password | Instance URL, Username | A group, a person or an event, with recent events |

## Observability

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [Datadog](/foliums/continuum-integrations/continuum-link/datadog) | Datadog credentials | Datadog site, content audience, saved detail, approved tag keys, Software Catalog, SLOs, default SLO window | Host, monitor, catalog service or reliability objective |
| New Relic | User API key | Region (optional) | Entity identity, alert severity, reporting state and tags |
| Dynatrace | API token | Environment URL | Entity identity and open problems by category, with a timeline |
| Elastic Observability | API key | Kibana URL | Alert rule identity, active count and execution status |
| Splunk Observability Cloud | Access token | Realm | Detector state, active incidents by severity, current signals |
| SolarWinds Observability SaaS | API token | Data centre | Entity identity, health state, maintenance and telemetry age |
| Grafana Alerting | Service account token | Grafana URL | Firing alerts for a label matcher, or one alert rule's state |

> [!IMPORTANT]
> Every cloud connector reaches its provider from Blueprintr over HTTPS and is blocked from private, loopback, link-local, carrier-NAT and metadata addresses. Any URL field in these tables must name a publicly reachable host: Grafana, Alertmanager, Kibana, Dynatrace environment, self-hosted GitLab, xMatters and ServiceNow included. An internal host needs one of the on-premise connectors below, and Grafana, Alertmanager, Elastic, Dynatrace and GitLab are not among them.

## Monitoring

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [LogicMonitor](/foliums/continuum-integrations/continuum-link/logicmonitor) | Bearer token | Company, content audience, saved detail, group scope, maintenance context, instance datapoints | Device, DataSource instance or resource group |
| [Auvik](/foliums/continuum-integrations/continuum-link/auvik) | API key | Region, Username, site scope, audience, saved detail, alert history period, optional sections | Device context and recent alert history |
| AWS CloudWatch | None | A verified AWS cloud connection and a region | An alarm with recent state changes, or a log group with event volume |
| Azure Monitor | Client secret | Tenant ID, Client ID, Subscription ID | Resource identity, alerts by severity, recent alerts |
| Google Cloud Monitoring | Service account key (JSON) | Project ID | Alert policy and its conditions |
| Prometheus Alertmanager | Password | Alertmanager URL, Username (optional) | Alert counts for a matcher, top labels, firing since |

CloudWatch is the one cloud connector that stores no credential of its own. It reuses a verified [cloud connection](/foliums/continuum-integrations/continuum-cloud), so the form offers a connection and region picker instead of a token field.

That connection's role needs nine CloudWatch and Logs actions the discovery role does not grant. The form lists them under `Required IAM actions for the backing role`; add them before expecting alarm or log-group data. On an organisation-mode connection the form also asks for a 12-digit member account id.

Alertmanager always requires a secret to save the connection. For an unauthenticated instance, leave `Username` blank and type any placeholder in `Password`. It is never sent without a username.

Google Cloud Monitoring shows alert-policy configuration only. Its panel states "Open incidents unavailable".

## Uptime and synthetics

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| Pingdom | API token | None | Check identity, uptime percentage, average response, state changes |
| Better Stack Uptime | API token | None | Monitor identity, SLA and incident counts, active incidents |
| UptimeRobot | API key | None | Monitor identity, recent health and window totals |
| Checkly | API key | Account ID | Check identity, sampled results, latest runs |
| Site24x7 | OAuth credentials (JSON) | OAuth client ID, Data centre (optional) | Monitor state, account-wide fleet status, current problem monitors |

## Service management and source control

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [Jira Cloud work items](/foliums/continuum-integrations/continuum-link/jira) | Atlassian sign-in | Site, counts-only | One work item, a saved filter or a JQL scope |
| [ServiceNow CMDB](/foliums/continuum-integrations/continuum-link/servicenow-cmdb) | Password | Instance URL, Username, Snapshot audience, Saved detail, Open work | Configuration item with lifecycle, environment, ownership groups and discovery dates; relationships from the CI's side with the total; optional open incident and change counts |
| GitHub | Fine-grained access token | Verification repository, optional organisation, enabled reads, audience and detail | Repository context scoped by branch/workflow, labels, environment and path; separate work and CI, optional deployment, commit and release evidence |
| GitLab | Access token | Instance URL (optional) | Project identity, activity, recent issues and pipelines |

> [!NOTE]
> GitHub and GitLab take a pasted access token. There is no sign-in button on the Continuum connection form; Jira is the only connector that signs you in.

## On-premise, through the local agent

These ten appear in the connector list but cannot be selected until the organisation has an enrolled agent online that can serve them. Until then the option is disabled and its label says why: set up an agent, the agent is offline, or upgrade the agent. Blueprintr never stores their credentials. Set in the agent's own configuration, a credential never leaves your network; sent from the Continuum Local panel instead (the agent must allow it), it passes through Blueprintr to the agent without being saved. The connection form has no credential field, and shows the account each product needs under its notice.

| Connector | Credential parts in the agent config | Other fields | Panel |
| --- | --- | --- | --- |
| SolarWinds Orion | `username` and `password` | Orion server URL | Node identity, health metrics, active alerts, interfaces, volumes |
| Zabbix | `token` | Zabbix frontend URL | Host identity, unresolved problems, current problems |
| PRTG Network Monitor | `token` | PRTG server URL | Device identity, sensor counts, unhealthy sensors |
| Checkmk | `username` and `password` | Checkmk URL, Site | Host identity, service states, current problems |
| Icinga 2 | `username` and `password` | API URL | Host identity, service states, active problems |
| ManageEngine OpManager | `token` | OpManager URL | Device identity, active alarms |
| WhatsUp Gold | `username` and `password` | WhatsUp Gold URL | Device identity and active monitor counts |
| NetBox | `token` | NetBox URL, Custom fields to show, Snapshot audience | Device or virtual machine identity, primary addresses, interfaces with MACs, addresses and cabled peers, and the listed custom fields |
| Infoblox | `username` and `password` | Grid Manager URL, WAPI version, Extensible attributes to show | A host, an address or a network: DNS records, IPAM state, DHCP leases and fixed addresses, network utilization and the listed extensible attributes |
| Veeam Backup & Replication | `username` and `password` | Backup server URL, REST API version, Restore point target | Protection verdict, age of the last good restore point, jobs protecting the machine and their last result, recent failures |

For SolarWinds Orion, Checkmk, Icinga 2 and Infoblox the username is part of the agent's credential, so the connection form does not ask for it. It shows what that account needs instead; set the username with the password, in the agent config or from the Continuum Local panel.

Each one wants a dedicated account that can only read, on a known port, and most need a certificate given to the agent. A port in the connector's URL replaces the default. [Certificates](/foliums/blueprintr-user-guide/continuum/local-agent#certificates) in the Continuum Local guide explains the certificate column.

| Connector | Least-privilege account | Default port | Certificate |
| --- | --- | --- | --- |
| SolarWinds Orion | No administrator, node management or unmanage rights | 17774 | Self-signed on install |
| Zabbix | Role type User, Read on the host groups to show | 443 | Depends on the install |
| PRTG Network Monitor | API key with Read access, Read-only user | 443 | Self-signed on install |
| Checkmk | Role copied from Guest, plus Read access to all hosts and folders | 443 | Depends on the install |
| Icinga 2 | ApiUser with `objects/query/Host` and `objects/query/Service` only | 5665 | Icinga's own CA |
| ManageEngine OpManager | API key with Read access only | 8060. Write it in the URL: without a port, the connector uses 443 | Self-signed on install |
| WhatsUp Gold | Read-only user that can read the Entire Network group | 9644 | Depends on the install |
| NetBox | View on devices, interfaces, IP addresses, VMs and VM interfaces only; Write enabled off | 443 | Depends on the install |
| Infoblox | Own admin group with API access and read-only permissions, no superuser | 443 | Issued to www.infoblox.com: replace it first |
| Veeam Backup & Replication | Veeam Backup Viewer role only | 9419 | Self-signed on install |

### NetBox

Supports NetBox 4.0 and later; verify refuses an older release, because before 4.0 NetBox ignores the list of fields Blueprintr asks for and would send config contexts. Enter the token alone, without the word Token or Bearer. v1 tokens are 40 characters; v2 tokens (NetBox 4.5 and later) begin `nbt_` and include the part after the dot. Either works. Blueprintr never asks for config contexts or comments. It asks for custom fields only when you list some under Custom fields to show; left blank, or set to `none`, no custom field value leaves NetBox. NetBox cannot send only some custom fields, so while any are listed, NetBox sends Blueprintr every custom field value on the device or virtual machine: panels show only the listed ones, and the rest are deleted with the request within minutes. A custom field named like a credential is never shown, even when listed. If you keep secrets in custom fields, leave the list blank. The panel is for Blueprint editors unless you choose all Blueprint readers.

### Infoblox

Leave the WAPI version blank on NIOS 8.6 and later (2.12). The certificate NIOS installs with is issued to www.infoblox.com, so replace it with one for the Grid Master's address before giving it to the agent as `caFile`; [Certificates](/foliums/blueprintr-user-guide/continuum/local-agent#certificates) has the steps. While any extensible attributes are shown, the grid sends Blueprintr all of an object's extensible attributes: panels show only the listed ones, and the rest are deleted with the request within minutes. Enter `none` and Blueprintr never asks for them. If you keep secrets in extensible attributes, use `none`. Panels are for Blueprint editors only, since leases and MAC addresses can identify people on client networks.

### Veeam Backup & Replication

Needs version 12 or later and agent 0.2.0 or later, which keeps Veeam's access token on the agent. On 12.0, set the REST API version to `1.1-rev0`. The build number in the verify message needs the Backup Administrator role, and is left out for a Backup Viewer. The tab measures a restore point's age on the backup server's own clock. A job that includes a machine through a folder, tag or cluster is found through the machine's restore points, not through the job definition. Panels are for Blueprint editors only.

## Reading any panel

Whatever the connector, the same rules hold.

- Data is fetched with the connection's credential, not the reader's. A source link opens the provider, which applies its own permissions.
- A panel is a named projection of the provider's response. The raw upstream object is never stored as-is.
- A failed read never becomes a zero. Sections are marked unavailable or partial, and partial counts are lower bounds.
- A provider that cannot be reached leaves the saved snapshot in place. The tab keeps its last successful body and the banner reads "Last refresh failed". A first link that cannot fetch is refused, so no tab is created.
- A saved panel reaches everyone who can read the blueprint unless its connector has an audience setting or keeps its panels for editors. Datadog, LogicMonitor, Auvik, Rootly, ServiceNow, GitHub and NetBox have the setting, and Infoblox and Veeam Backup & Replication panels are always for Blueprint editors only. On a public blueprint every other panel is visible to anonymous readers, embeds and exports.
- Counts describe what was retrieved at the stated time. They are not a statement that the component is healthy now.

---

# Continuum Integrations: PagerDuty
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/pagerduty

> Service ownership, open incident state and on-call coverage beside the component they belong to.

Link a PagerDuty technical service to the stratum for the component it covers. The saved tab shows who owns the service, what is open against it, and whether the primary escalation level had cover when it was fetched. Responding to incidents stays in PagerDuty.

A PagerDuty technical service is the only object that can be linked. Business services appear inside a service's panel as related rows, and cannot be linked on their own.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and `continuum_integrations.manage` on the connection's organisation or team.
2. In PagerDuty, create a dedicated read-only REST API key under `Integrations → Developer Tools → API Access Keys`. An Events API integration key will not work here. If you paste one, Blueprintr sends it and PagerDuty rejects it with "PagerDuty services read failed (HTTP 401). Check or replace the REST API key."
3. In Blueprintr, open `Settings → Continuum` on the organisation or team, go to `Operational integrations`, choose `New integration`, and select PagerDuty as the `Type`.
4. Give the connection a `Name`, set the two options below, paste the key into `API token`, and choose `Connect & verify`. Without a name the form refuses with "Give this integration a name."

### Connection options

Both dropdowns open on `Use default`, which stores nothing and behaves as the first real option.

| Field | Options | Effect |
| --- | --- | --- |
| `PagerDuty region` | Use default, United States (US), Europe (EU) | Chooses the API host. Use EU for accounts whose address ends in `eu.pagerduty.com`. Default is US |
| `Imported content` | Use default, Summary (recommended), Detailed: include titles and description | Detailed adds incident titles and the service description. Default is Summary |

Verification makes two list calls, one for services and one for incidents. Both may return nothing and still verify, so a successful check proves the key reads those collections, not that the account has content. On-call coverage and service dependencies are not exercised at verification time, so they may still fail when a service is linked.

## Link a service

Open the stratum and choose `Continuum Link`, then search by any of these. PagerDuty has no prefix syntax.

| What you type | What happens |
| --- | --- |
| A service name | Searches service names, up to about 300 services |
| A service ID (6 to 32 uppercase letters and digits) | Looked up directly. If PagerDuty returns 404, the same text is searched as a name |
| A PagerDuty service URL | The ID is read out of `/service-directory/<ID>` or `/services/<ID>`. The URL itself is never called |

A URL from the other region is refused rather than looked up: "This PagerDuty service URL belongs to a different region. Choose the matching connection."

## What the panel shows

| Section | Contents |
| --- | --- |
| Service | Service, Service ID, Region, Incident posture, Meaning, Owning team, Escalation policy, and the description in Detailed mode |
| Open incidents | Counts of reported open, high-urgency, low-urgency, unknown urgency and unknown status |
| Incident coverage | Retrieval, time range, content mode, how many incidents are shown, and a consistency row when the two reads disagree |
| Open incident details | Up to 20 incidents, newest first |
| Ownership in PagerDuty | Links to the escalation policy and the owning team |
| On-call coverage | Whether the primary level had cover, when to recheck, and a privacy note |
| Service relationships | Retrieval state, then a table of related services |

The headline restates PagerDuty's service status: "No open incidents reported", "Acknowledged incidents", "Triggered incidents", "Maintenance · new incidents suppressed" or "Disabled · new incidents suppressed". The Meaning row spells out the limit of that reading: "PagerDuty incident and notification state; not a measurement of component availability."

If the service read and the incident read disagree, the headline is replaced with "Service and incident state disagree · refresh to recheck" rather than showing a healthy state.

### Counting and its limits

Open incidents are those PagerDuty reports as triggered or acknowledged, with no creation-date cutoff. Retrieval stops after five pages of up to 100, so roughly 500 incidents. When that cap is reached, the section title gains "partial retrieval", every count gains a trailing plus sign, and the Retrieval row reads "Partial: stopped after 5 pages; counts are lower bounds."

On-call coverage is computed over one hour starting at the fetch, filtered to the service's escalation policy. If those pages could not all be read, coverage reads Unknown rather than claiming a gap: "Coverage retrieval is partial; absence does not establish a coverage gap." A service with no escalation policy makes no on-call call at all.

Related services are limited to six detail lookups. Business services never carry a state, showing "Business impact not retrieved", because the connector does not infer business impact.

## What is never imported

Responder names, user IDs, email addresses and schedule names are excluded in both content modes. So are incident bodies, assignees, acknowledgers, conference-bridge numbers, service integration keys and business-service points of contact. Detailed mode adds exactly two fields: the incident title, truncated to 250 characters, and the service description, truncated to 1000 characters.

Only `pagerduty.com` HTTPS links reach the panel, with query strings and fragments stripped.

## Audience

PagerDuty declares no audience setting, so its saved panel is visible to everyone who can read the stratum. On a public blueprint that includes anonymous readers, embeds and exports. Service names, team names and relationships are visible even in Summary mode.

Choose `Detailed` only when incident titles and the service description are appropriate for that audience. Reducing detail later applies to subsequent refreshes and does not recall copies already shared.

## Changing the region later

Changing the region is refused while any binding predates the region setting: "Remove the existing legacy bindings before changing PagerDuty region, then link services from the new region."

If every binding does carry a region, the change is allowed, and each of those services then fails on refresh with "This service was linked in a different PagerDuty region. Unlink it and choose the service again." The new region is verified with the existing credential before it saves, so a US-only key fails the switch to EU and the previous setting is kept.

## Refreshing and recovery

Snapshots become due for refresh after five minutes, which is a reminder rather than automatic polling. A failed service or incident read keeps the previous snapshot and adds a warning; it never becomes a healthy zero. A failed on-call or dependency read marks only that section unavailable and still saves the panel.

---

# Continuum Integrations: incident.io
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/incident-io

> Catalog service context and the incidents attached to it, beside the component on the diagram.

Link an incident.io Catalog entry to the stratum for a service or component, and the tab shows the incidents that named it. Link an incident instead, and the tab explains one response: its lifecycle, severity, measured durations and follow-up state. Responding and writing up stay in incident.io.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and `continuum_integrations.manage` on the connection's organisation or team.
2. In incident.io, create a dedicated key under `Settings → API keys` with `View data` (`viewer`) and `View catalog` (`catalog_viewer`). Leave write permissions and `View all incident data` (`global_access`) disabled.
3. In Blueprintr, open `Settings → Continuum`, go to `Operational integrations`, choose `New integration`, and select incident.io as the `Type`.
4. Give the connection a `Name`, paste the key into `API key`, set any of the optional fields below, and choose `Connect & verify`.

Verification reads the key's identity, one incident, the Catalog type list, one Catalog entry, the custom-field list when relationship fields are configured, and one follow-up when remediation counts are on. All requests are reads against `api.incident.io`.

### Optional connection settings

Every field can be left blank. The three list fields accept up to 50 comma-separated IDs each. Ask your incident.io administrator for the stable IDs.

| Field | Blank behaviour | What it changes |
| --- | --- | --- |
| `Catalog types to search` | Searches available types within the retrieval budget | Restricts search to the service or component types your diagrams use |
| `Incident relationship fields` | An incident counts if it selects the entry in any custom field | Counts an incident only when it selects the entry in the listed fields, such as Affected services |
| `Catalog details to share` | No attributes are shown at all | Adds selected structured attributes, such as owning team or tier, visible to every blueprint reader |
| `Recent incident history (days)` | 30 | The window for the "created in the last N days" count. Accepts 1 to 90 |
| `Include remediation counts` | Off | Adds aggregate follow-up state. Needs the `actions.view` permission and the matching incident.io entitlement |

Active, triage and paused incidents are checked regardless of age, so the history window only bounds the recent-history count.

## Link an object

Open the stratum, choose `Continuum Link`, and search. Once an incident.io connection is in play, an `incident.io objects` selector appears with `Catalog and incidents`, `Catalog records` and `Incidents`. Search a name, a stable ID, an INC number or an incident link.

| What you type | What it finds |
| --- | --- |
| A name | Catalog entries, incidents, or both, depending on the selector |
| `INC-1042` or a bare number | That incident directly, including one older than the history window |
| A 26-character ULID or a UUID | That record directly |
| An `app.incident.io` incident link | That incident directly |

Typing `catalog:` or `incident:` in front of a query narrows it the same way the selector does.

## What is always excluded

Blueprintr applies its own filter before anything reaches a panel, whatever the key is permitted to read.

- An incident appears only when incident.io marks it organisation-visible and its mode is standard or retrospective. Private, test, tutorial and stream incidents never appear. Linking one returns "incident.io incident is private, unavailable, or a test record and cannot be linked."
- A Catalog type that represents people or customers is dropped, whether by its category or by user, person, customer, contact or employee appearing as a word in its name. Linking an entry of that type fails, but the reason is not shown: the editor sees the generic "incident.io could not be reached", so check the type's category and name before suspecting the connection.
- Only three shapes of Catalog attribute can be shared: numeric, boolean, and a relationship to a team, service or product-feature type. Free text is excluded. An attribute whose name suggests a secret, a token, an email address or a phone number is excluded even when its type is numeric, and selecting it fails verification.

Approved attribute values are clamped further: at most 10 records per attribute, numbers must parse as numbers, and a relationship label must be 160 characters or fewer with no line break and nothing shaped like an email address.

## What a Catalog panel shows

| Section | Contents |
| --- | --- |
| Catalog entry | Name, Type, ID, External ID, Catalog state, Updated |
| Related incidents | Active, Triage, Paused, created in the last N days, Coverage, Relationship |
| Approved Catalog relationships and metadata | The attributes you selected, or nothing when none are configured |
| Related incident details | Up to 10 incidents, open first and then newest first |

The Coverage row states the limit of the reading: "Organization-visible standard and retrospective incidents only; private records are excluded. A related incident does not by itself establish component health."

The headline is one of: "Archived Catalog entry", "Related incident coverage incomplete", a count of related active incidents, a triage and paused count, or "No related active incidents in available scope".

## What an incident panel shows

Reference, lifecycle, status, severity, whether a lead is assigned, and created and updated times. The lead row reads Assigned, Unassigned or Unknown, and never names the person. Below that sit measured durations with their availability, the incident's timestamps, and links out to the incident, the postmortem and any linked issue.

With remediation counts on, a `Follow-ups` section adds outstanding, completed, not-doing and unknown-status totals. Descriptions and assignees are not imported.

## Partial results

Retrieval is bounded. When a page limit or budget is reached, counts are prefixed "At least", the panel adds a coverage-incomplete section, and the snapshot is marked partial. A count from a partial read is a lower bound, never a total.

Common messages an editor sees:

- "incident.io needs Catalog read access. Ask the connection owner to enable catalog_viewer and Verify in Settings → Integrations."
- "incident.io needs actions.view access for remediation counts. Enable that read permission or turn off remediation counts, then Verify."
- "incident.io results are incomplete. Narrow the Catalog types or search scope, then retry; open incident.io for the full view."
- "incident.io request limit reached. Wait a minute, then retry."

## Audience and refreshing

incident.io declares no audience setting, so its saved panel reaches everyone who can read the stratum, including anonymous readers of a public blueprint. Incident references, names, severities and any approved Catalog attributes are visible to them. In incident.io, organisation-visible does not mean suitable for the public, so review a record before linking it.

Snapshots become due for refresh after five minutes, as a reminder rather than automatic polling. A failed refresh keeps the previous snapshot with a warning. Changing a setting applies to later fetches and does not rewrite copies already saved or shared.

---

# Continuum Integrations: Jira
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/jira

> Jira work items and Jira Service Management Operations alerting, connected through Atlassian sign-in.

Blueprintr connects to Atlassian three separate times, for three separate jobs.

| Connection | What it reads or writes | Gate |
| --- | --- | --- |
| Jira Cloud work items | Work items, saved filters and JQL scopes, on a stratum | Enterprise, `continuum_integrations.manage` |
| Jira Service Management Operations | Alerts, Operations teams and on-call schedules, on a stratum | Enterprise, `continuum_integrations.manage` |
| Jira follow-up destination | Creates an issue from a stratum | `webhook.manage` on the organisation, no plan gate |

The first two are Continuum Link connectors. The third is a write path and is covered at the end of this page.

## Connecting

Both read connectors are created only through Atlassian sign-in. On the `New integration` form, choosing either provider hides the Name field, the config fields and the secret field, and offers `Connect with Atlassian` instead. Pasting a token is refused: "Connect this integration through Atlassian sign-in."

After consent you choose an Atlassian site, name the connection, and decide the counts-only setting. Only sites that granted every required scope are offered. If none did, you see "No Jira Cloud site granted the required access. Check the app's permissions and your Jira membership, then reconnect."

Scopes requested are fixed per connection:

| Connection | Atlassian scopes |
| --- | --- |
| Jira Cloud work items | `offline_access`, `read:jira-work` |
| Jira Service Management Operations | `offline_access`, `read:ops-alert:jira-service-management`, `read:ops-config:jira-service-management` |
| Jira follow-up destination | `offline_access`, `read:jira-work`, `write:jira-work` |

Blueprintr verifies the connection with a read before saving it, and creates no test issue. A connection's site cannot be edited afterwards: the row offers `Reconnect with Atlassian` rather than `Configure`, and reconnecting is pinned to the original site.

> [!NOTE]
> These connections need an Atlassian OAuth app configured on the Blueprintr deployment. Where that is missing, connecting fails and tells you to ask your Blueprintr administrator.

## Counts-only

A checkbox on the site-selection page reads "Import counts and operational state only. Omit work item summaries, alert subjects and query details from blueprint snapshots."

> [!IMPORTANT]
> Counts-only is one way. Once set, the checkbox is disabled and no path turns it back off. Reconnecting cannot clear it either.

It removes the free text from both the rendered tab and the stored payload:

| Object | Removed | Kept |
| --- | --- | --- |
| Work item | Key and summary, type, project, parent, components, target versions, related work | Status, status category, priority, resolution, due date, updated time |
| Query or filter | The JQL, the saved-filter name, and the per-item list | Match count, audience, search consistency, status-category counts |
| Alert scope | The query text, the matching line, the Operations team, both alert lists | Open, unacknowledged and snoozed counts, coverage, recent history, per-priority counts |
| On-call schedule | Schedule name and owning team | Counts, timezone, checked-at |

Candidate titles also become neutral, such as "Jira work item" and "JSM alert scope", which is what a stratum minted by Scan is named.

## Searching Jira Cloud work items

The syntax hint appears on the connection row in settings, not in the stratum search box: "Link a work item, filter:123, epic:PROJ-123, or jql: followed by a query."

| What you type | What it does |
| --- | --- |
| `PROJ-123` | Links that work item |
| A `/browse/KEY-123` URL on the connected site | Links that work item |
| `filter:12345` | Binds the saved filter by ID. Its JQL is re-read on every refresh, so editing it in Jira changes the tab |
| `epic:APP-42` | Work under that epic |
| `jql:` followed by a query | That query |
| Anything else | Searched as a quoted phrase against summaries, never as raw JQL |

Queries are capped at 2,000 characters. A link from a different Atlassian site is refused without making a request: "This Jira link belongs to a different site. Choose that site's integration."

A query panel reads at most 250 work items. Past that, the count is a lower bound and the panel says "Showing at most 250 matching work items. Open Jira for the full result."

A bound work item shows work item, type, project, status, status category, priority, resolution, due date and last update, plus parent, components, target versions and related work when present. A missing value reads "Not set or unavailable" rather than a healthy default. Descriptions, comments, assignee and reporter are never fetched.

> [!TIP]
> A work item marked Done does not mean the service it refers to is healthy.

## Searching Jira Service Management Operations

The hint on that connection row reads "Search entity or subject text, query: for an Operations query, team: or schedule:."

| What you type | What it does |
| --- | --- |
| Plain text | Matches entity or message text |
| `query:` followed by an Operations expression | Uses that expression |
| `team:` followed by text | Finds an Operations team |
| `schedule:` followed by text | Finds an on-call schedule |

> [!IMPORTANT]
> Operations query syntax is not JQL. Sending a JQL string returns "JSM Operations rejected this query (HTTP 400|422). Check the Ops search syntax; Jira JQL is not supported here."

Queries are capped at 1,000 characters.

An alert panel makes two independent reads on each refresh: current open alerts matching the saved query, up to 500, and a separate newest-15 history page. A large volume of newer closed alerts therefore cannot hide an older open one.

The headline follows a strict order. Any open P1 or P2 makes it critical. An unknown priority or an incomplete read makes it "open alerts · status incomplete". Zero open alerts reads "No open alerts in this query" only when retrieval was complete, every priority was known and nothing else warned; otherwise it reads "No open alerts · recent history unavailable". Partial results never read as an all-clear: the Coverage row says "Partial retrieval; this is not an all-clear" and counts are prefixed "At least".

An on-call schedule panel reports schedule, owning team, counts of current people on call, current team and escalation routes, next people on call, timezone and when it was checked. Individual responder identities and contact details are never returned or stored. Where routing is by team or escalation only, the status reads "On-call routing configured; person coverage unconfirmed" rather than naming anyone as on call.

## Freshness and audience

| Snapshot | Marked due for refresh after |
| --- | --- |
| Jira work item or query | 15 minutes |
| JSM alert scope | 5 minutes |
| JSM on-call schedule | 2 minutes |

Neither connector sets an audience, so both panels reach everyone who can read the blueprint, including anonymous readers of a public blueprint, embeds and exports. Counts-only is the control for that exposure, and it applies from the next refresh onward rather than rewriting saved snapshots.

## Creating a Jira follow-up from a stratum

Configure a Jira destination on the organisation's `Settings → Continuum` page. Choose `+ New webhook`, set the destination to Jira, then choose `Connect Jira account` to sign in with Atlassian a second time and grant `write:jira-work`.

> [!IMPORTANT]
> A connection made for Continuum Link holds read access only. It is listed as "(read access only)" and cannot be chosen. The write connection is a separate sign-in.

Pick the project, work type and required fields, then use `Verify without creating a work item` before saving. The work type must have Description on its Jira creation screen, or the destination is refused. Every required field on that screen without a Jira default must also be given a value here.

The `Jira follow-up` button then appears in the stratum tab strip for an author who can edit the blueprint and holds `webhook.manage` on the owning organisation. A blueprint with no owning organisation never shows it.

The dialog is titled `Create Jira follow-up` and asks for a destination, a summary of up to 240 characters prefilled as "Follow up: <stratum name>", and what needs to happen, up to 12,000 characters. `Create Jira issue` submits it. Your own submission is the approval step; nobody else reviews it. The text is recorded durably before Jira is contacted, so a retry cannot create a second issue, and reusing a request with different text is refused.

The created issue links back to the stratum. Its key can then be linked through the Jira Cloud connector to follow progress.

New destinations create follow-ups manually only. Automatic creation is opt-in and limited to four events: a blueprint being published, and a workflow run being submitted, approved or rejected.

> [!NOTE]
> The write connection has no plan gate. An organisation holding `webhook.manage` can create follow-ups without Enterprise, even though it cannot use Continuum Link to read Jira back.

---

# Continuum Integrations: Rootly
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/rootly

> Incident response, service context and follow-up progress beside the component they explain.

Connect a Rootly service to the stratum for a system component, or link an incident to the stratum explaining a failure or recovery process. Readers can understand the response in the diagram's context and open Rootly for the full incident record. Blueprintr reads information; incident management stays in Rootly.

## Connect and choose an object

1. You need an Enterprise licence, edit access to the blueprint, and `continuum_integrations.manage` on the connection's organisation or team.
2. In Rootly, open `Organization Settings → API Keys → Generate New API Key`. Prefer a dedicated `Global API key` assigned read-only Incident Response and, only if needed, On-Call roles. Personal keys inherit their creator's access; Team keys inherit Team Admin permissions. See [Rootly's API-key guide](https://docs.rootly.com/api-reference/overview).
3. In Blueprintr, open `Settings → Continuum` on the organisation or team, go to `Operational integrations`, and choose `New integration`. Select `Rootly` as the `Type`, give the connection a `Name`, enter the `API key`, review the audience and optional settings, then choose `Connect & verify`. Verification checks service and incident reads. There is no separate enable step.
4. Save the blueprint, open the relevant stratum, and choose `Continuum Link` from its `+ Add tab` menu. Search for the service or incident and review its identity before linking. `Suggest integrations…` on a shape and `Scan for integrations` across the blueprint both propose Rootly matches, and attach nothing until you apply them.

Blueprintr uses Rootly's hosted API at `api.rootly.com`. This connection does not provide an alternative regional or self-hosted endpoint.

## Choose the information and audience

| Setting | Default | What it changes |
| --- | --- | --- |
| Rootly content audience | Blueprint editors | Keeps saved Rootly details visible to blueprint editors. Choose the reader-visible option, `All Blueprint readers`, only after approving the information for everyone who can read the blueprint. Its full label adds "approved metadata". |
| Service ownership and context | On | For linked services, adds related services, teams, environments, repository names and deployment names. Turn it off to omit optional context reads. |
| On-call coverage | Off | For linked services, adds [on-call coverage](https://docs.rootly.com/api-reference/oncalls/list-on-calls) when the key and Rootly account support it. Individual responders and their contact details are omitted. |
| Incident action item counts | On | For linked incidents, adds aggregate task and follow-up progress from [incident action items](https://docs.rootly.com/api-reference/incidentactionitems/list-incident-action-items). Task descriptions and assignees are omitted. |

The baseline key needs read access to `services and incidents`. Context may also require team and environment reads; follow-up summaries need incident action-item reads. On-call coverage needs access to Rootly's on-call data and the relevant product entitlement. These are permissions on the key's assigned roles, not OAuth scope strings. Disable an optional capability instead of granting unrelated administrative access.

Rootly incidents marked private, or without a reliable privacy designation, are excluded from selection and saved incident data under either audience setting. Rootly's non-private designation does not itself make an incident appropriate for the public. Review titles, service names and relationships before switching to the reader-visible audience.

> [!NOTE]
> Under the editor audience, a candidate is offered under a generic title such as "Rootly service" or "Rootly incident INC-42" rather than its real name, because a candidate title can become a stratum filename and a filename sits outside the audience gate. A stratum minted from one of these is named accordingly.

## Read the snapshot

A service panel separates active response from recent history and maintenance. Normal incidents and sub-incidents are distinguished by kind; test incidents do not count as production incidents. The active view is independent of the 30-day history window, so an older unresolved incident can still be relevant. Maintenance has its own state and planned window when available; it does not become an outage merely because it is in progress. Rootly documents these filters in its [incident API](https://docs.rootly.com/api-reference/incidents/list-incidents).

An incident panel shows response state, severity, related services and lifecycle times when available. `Mitigated` means impact has been reduced or halted; it does not mean response work is complete. Follow-up progress helps distinguish incident resolution from outstanding improvement work. Open Rootly to read descriptions, communicate with responders or change the record.

Opening a tab displays saved data. Re-fetch with the circular-arrows icon on the linked row, whose tooltip reads "Re-fetch this integration's data". Rootly snapshots indicate that another refresh is needed after five minutes; this is a freshness warning, not automatic polling. On-call coverage is limited to the time checked. Incident counts describe retrieved records, not a guarantee that the system is healthy.

## Missing information and recovery

An unavailable incident list, incomplete pagination or unreadable optional section is shown as unavailable or partial, rather than as zero incidents or no outstanding work. If a whole refresh fails, the prior snapshot remains with a warning. Check the key's role and expiry; for rate limits, wait for the stated retry interval before refreshing again.

Rotate a credential with `Rotate token`, then `Verify & replace`, which swaps it only if the new key verifies. `Suspend` stops search and refresh while leaving saved snapshots readable, and `Resume` restarts it. The broken-link icon on the linked row removes the binding. The connection can be deleted after its bindings have been removed.

## Copies and rollout checks

New snapshots restricted to editors use Blueprintr's existing audience controls for readers, embeds, viewer exports and search or AI indexing. Editor exports and backups retain the source. Approved reader-visible snapshots follow the blueprint's audience, including anonymous readers of a public blueprint.

Settings apply to subsequent fetches. Restricting the audience does not rewrite panels already saved: refresh each linked tab successfully, or unlink it, before treating existing Rootly content as editor-only. Changing the audience also does not rename existing strata or link labels, or remove authored notes outside the managed panel. Templates, version history, exports and other existing copies are not retroactively rewritten or recalled by an audience change, key revocation or unlink.

Before operational rollout, verify the connection against your Rootly account: service membership, a known older active incident, maintenance, private-incident exclusion, optional permissions and on-call coverage. Local fixture tests do not establish your account's entitlements or replace this live check.

---

# Continuum Integrations: Datadog
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/datadog

> Monitor conditions, service ownership and selected reliability objectives beside the component they explain.

Connect Datadog to the stratum for a component on your diagram. Use a host to explain telemetry reporting, a monitor to explain an evaluated condition, a catalog service to explain ownership and dependencies, or an SLO to show performance against an objective. Open the linked Datadog record for detailed investigation and operational changes.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and `continuum_integrations.manage` on the connection's organisation or team.
2. Create a dedicated Datadog service account with read permissions. Follow Datadog's [key setup](https://docs.datadoghq.com/account_management/api-app-keys/) or [Service Access Token guide](https://docs.datadoghq.com/account_management/service-access-tokens/).
3. In Blueprintr, open `Settings → Continuum` on the organisation or team, go to `Operational integrations`, choose `New integration`, select `Datadog` as the `Type`, enter a `Name`, and choose the `Datadog site`. If you use a custom Datadog domain, find the underlying site in `My Preferences`. See [Datadog sites](https://docs.datadoghq.com/getting_started/site/).
4. Under `Datadog credentials`, set `Credential type` to `API key and application key`, or to `Service Access Token` and fill that field. A Service Access Token pasted into the application-key box is rejected.
5. Review the information and audience settings, then choose `Connect & verify`. Blueprintr stores credentials encrypted and never displays them after saving.

Hosts and monitors require `hosts_read` and `monitors_read`. Enable optional capabilities only when needed:

| Capability | Additional permission | Information saved |
| --- | --- | --- |
| Service Definitions, schema v2.2 and earlier | `apm_service_catalog_read` | Service ownership and structured operating links |
| Software Catalog, schema v3 | `apm_service_catalog_read` | Supported catalog entities, owners and declared or discovered relationships |
| Reliability objectives | `slos_read` | Selected SLO target, performance, observation window and error budget |

Catalog versions use distinct APIs. Choose the one your account uses and verify availability on your site. Datadog sites are independent and product availability differs. The connection reads existing information; it does not create monitors, SLOs, public dashboards or new telemetry instrumentation. Your existing Datadog entitlements and API limits still apply.

## Choose the component's operational context

Save the blueprint, open its stratum, and choose `Continuum Link` from the `+ Add tab` menu. Search by host or monitor name, paste a Datadog monitor, SLO or infrastructure source link, or use one of these forms:

| Search | Use |
| --- | --- |
| `monitor:12345` | Select an exact monitor |
| `service:checkout env:production` | Find the catalog service for this deployment |
| `slo:0123456789abcdef0123456789abcdef` | Select an exact SLO |
| `slo-id:objective-id` | Explicitly select an SLO by its exact ID, including other supported ID formats |
| `slo:Checkout availability` | Find a named objective |

Review the connection, stable identity and source preview before linking. Catalog and SLO searches require the corresponding connection option.

Linking a Datadog `service` requires its exact `env` tag value, without spaces or wildcards. For other Catalog entity kinds the field reads `Environment (optional)` and may be left blank. The service identity and deployment environment serve different purposes; changing a deployment's `version` tag does not make it a new service. [Unified service tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/) explains Datadog's `service`, `env` and `version` relationships.

Add an explicitly selected SLO ID to a service and choose its window. Check that the objective describes this service and environment: a similar name is not proof of that relationship. Standalone SLO selection also lets you choose 7, 30 or 90 days, where supported by the objective.

For a multi-alert monitor, optionally copy the exact Datadog group string to show that group's state. Without a group, the panel describes the monitor's aggregate state. One monitor may cover many hosts or environments; its aggregate alert is not proof that every component is affected.

`Suggest integrations…` and `Scan for integrations` offer matches for review. Use manual search when you want to choose an environment, SLO or monitor group. Each connection has one managed tab per stratum; choosing a different object explicitly replaces its binding. Authored prose and diagram content stay intact.

## Read the saved information

Host reporting means whether Datadog received the expected metrics. Missing telemetry is not proof that a host is down. Hosts outside Datadog's available inventory window can become unavailable. Monitor panels retain distinct alert, warning, no-data and other provider states; these are evaluated conditions, not a general guarantee of system health.

Catalog v3 separates declared relationships from those Datadog discovers through APM or Universal Service Monitoring. If provenance cannot be established, it is labelled unknown. These relationships are catalog-wide; the selected monitor environment does not filter this topology. The earlier Service Definitions API supplies ownership and links, with no relationship retrieval. Catalog navigation opens your regional Software Catalog; use the displayed entity identity to locate the component. Structured operating links may include documentation, runbooks and dashboards recorded on the selected entity. Blueprintr does not discover every dashboard or publish dashboard contents.

SLO panels show the objective's target and calculated performance for the selected window. Error budgets retain their units and may be negative when the budget is exhausted. Blueprintr never substitutes 100% for an unavailable calculation. Datadog's own no-data rules still apply: monitor SLOs follow the underlying monitors' settings, and time-slice SLOs count no-data periods as uptime. The panel explains these limits. See Datadog's [SLO history](https://docs.datadoghq.com/api/latest/service-level-objectives/get-an-slos-history/) and [monitor details](https://docs.datadoghq.com/api/latest/monitors/get-a-monitors-details/).

Opening a tab displays its saved snapshot. Re-fetch with the circular-arrows icon on the linked row ("Re-fetch this integration's data"). Snapshots show their retrieval time and become due for refresh after five minutes; this is a freshness warning, not automatic polling. Incomplete retrieval is labelled partial. Counts from a partial list are lower bounds; an unavailable section does not mean zero. A failed refresh keeps the previous snapshot with a warning.

## Information and audience

New connections default to `Blueprint editors` and `Summary`. Summary retains the identity and operational measures while keeping monitor detail to a minimum. Detailed mode can include monitor names and approved tag values; new connections approve only `service`, `env` and `version` tag keys initially. Enter `none` to omit tags; clearing a configured list also omits tags on the next refresh. Monitor messages, notification recipients and raw telemetry are omitted.

Choose the reader-visible option, `All Blueprint readers`, whose full label adds "approved metadata", only after reviewing the information for that audience. A public blueprint can have anonymous readers who do not authenticate to Datadog. Host identities, service names, ownership, links and even selected tag values may be confidential.

> [!IMPORTANT]
> A connection created before these settings existed has no stored value for audience, saved detail or approved tag keys. Each absent value resolves to its legacy behaviour: blueprint readers, detailed, and every tag key up to 30, excluding keys whose name suggests a secret. Such a connection publishes monitor names and all tag values to everyone who can read the blueprint.
>
> Opening `Configure` and saving unchanged keeps that behaviour, because the form pre-selects the legacy values. Select `Blueprint editors` under `Datadog content audience`, choose `Summary` under `Saved detail`, set `Approved tag keys` or enter `none`, choose `Verify & save settings`, then refresh each linked tab.

Settings affect subsequent successful refreshes; they do not rewrite existing snapshots. Editor-only panels follow the shared reader, embed, viewer-export and search or AI audience controls. Editor exports and backups can retain the source data. Names in authored notes or link labels outside the managed panel need separate review.

Unlinking, reducing detail, revoking credentials or changing audience does not recall saved versions, templates, exports, AI answers or copies already shared.

## Recovery and disconnection

Verification checks the required reads and enabled optional capabilities. Host and monitor reads must pass. If an enabled Catalog or SLO check fails, the connection stays usable for hosts and monitors and the verification notice shows which optional access needs attention. After reloading settings, use `Verify` to recheck optional availability; the stored verified status alone does not establish it.

If access is denied, check the site's selection, credential expiry and exact read permissions. Scoped keys do not inherit extra permissions. Newly created keys can take a few seconds to propagate. For rate limits, wait for the stated retry interval before refreshing; see [Datadog's rate-limit guidance](https://docs.datadoghq.com/api/latest/rate-limits/).

Use `Rotate token`, then `Verify & replace`, for credentials. Replacing an application key while keeping the same API key preserves links. Changing the API key or Service Access Token requires reviewing and linking objects again, because Blueprintr cannot assume the new credential addresses the same account. Changing sites also requires relinking. Older bindings must be unlinked before these changes. A failed credential verification preserves the previous credential.

`Suspend` stops search and refresh while retaining snapshots, and `Resume` restarts it. The broken-link icon on the linked row removes the binding and its managed tab. Remove all bindings before deleting a connection. Remove its stored credential and revoke it in Datadog when access should end.

Before operational rollout, validate your site's permissions, known host and monitor groups, missing telemetry, large result sets, SLO calculations, optional Catalog availability and regional source links against your own account. Local fixtures do not establish live product availability or account entitlements.

---

# Continuum Integrations: LogicMonitor
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/logicmonitor

> Resource, instance and group monitoring context beside the component your diagram explains.

Link a LogicMonitor device, DataSource instance or resource group to the stratum for the component it describes. A server can show the conditions affecting it; a circuit can show the exact monitored interface; a site can show the observed state of its group members. Investigation, alert acknowledgement and configuration changes remain in LogicMonitor.

## Connect your portal

1. You need an Enterprise licence, blueprint edit access and `continuum_integrations.manage` on the connection's organisation or team.
2. In LogicMonitor, create a dedicated [API-only user](https://www.logicmonitor.com/support/adding-an-api-only-user). Assign a role with `Resources View` on only the resource groups Blueprintr should read. Device, group, alert, instance, metric and scheduled downtime reads use resource permissions. Write, alert acknowledgement and Collector settings permissions are unnecessary. See [Resources role permissions](https://www.logicmonitor.com/support/resources-role-permissions).
3. Create a `Bearer` [API token](https://www.logicmonitor.com/support/api-tokens-2) for that user. This connector accepts Bearer tokens. LogicMonitor also supports LMv1 authentication, but an LMv1 access ID and key pair cannot be pasted into this connector's Bearer field.
4. In Blueprintr, open `Settings → Continuum` on the organisation or team, go to `Operational integrations`, choose `New integration`, select `LogicMonitor` as the `Type`, and enter a `Name`, `Company` and `Bearer token`. For `https://acme.logicmonitor.com`, enter `acme` as the company.
5. Review the content audience, saved detail and optional settings below, then choose `Connect & verify`. Verification checks resource and alert reads with the supplied credential. A successful check with no visible devices is explained separately: review the user's resource-group access or add monitored resources. Verification does not establish complete coverage or verify every optional read. Save the blueprint before adding a link.

This connection uses REST v3 on commercial `logicmonitor.com` portals. The portal host is always built as `<company>.logicmonitor.com`, so LMforGov portals and custom API hosts cannot be reached. No local agent is required. Credentials are encrypted and are not displayed again after saving. LogicMonitor documents the supported authentication methods in its [REST authentication guide](https://www.logicmonitor.com/support/rest-api-authentication).

## Choose the object your diagram describes

Open the stratum for your server, interface or site and choose `Continuum Link` from its `+ Add tab` menu. Only a rich stratum can host a linked tab. Search its name, hostname or IP, or paste a current UIv4 device or group resource URL from the portal.

Review the connection, company, object type, stable ID and instance lineage before choosing `Link object`, especially when names repeat. A successful first fetch is required before the binding is saved. One connection can have one linked object on a stratum; selecting another explicitly replaces that connection's previous link.

| What the stratum describes | How to select it | What to check |
| --- | --- | --- |
| A server or network device | Search a name, hostname or IP, or use `device:42` for an exact device ID. | Confirm the company and device identity; the same display name can exist more than once. |
| An interface or monitored component | Find its device, choose `Browse instances`, then select the instance. `instances:42` also lists instances on device 42. | Confirm the device, device-specific DataSource and instance. A DataSource's global ID is different from its device-specific DataSource ID. |
| An exact known instance | Use `instance:42:123:456`: device ID 42, device DataSource ID 123, instance ID 456. | Retain all three IDs; an instance name or portal instance URL alone does not establish its complete identity. |
| A site or service group | Search a group name or use `group:London` or `group:7`. | Confirm the group path and displayed direct or descendant scope. Membership describes an administrative monitoring group, not an architectural dependency. |
| A device within a group | Choose `Browse members` or use `members:7`. | This lists direct members. Browsing changes the search; it does not save a link. |

`Suggest integrations…` and `Scan for integrations` can help match diagram identifiers. Every suggestion still needs your review. Search results are limited to what the dedicated LogicMonitor user can read; no match does not prove that the object does not exist. Resolve any reported search or coverage warning before relying on absence.

## Choose detail, scope and audience

These settings belong to the connection. Detail, audience, maintenance and datapoint changes apply to subsequent fetches. The group scope is saved with the selected object: review and relink a group to change its scope.

| Setting | New connection default | What it changes |
| --- | --- | --- |
| LogicMonitor content audience | Blueprint editors | Restricts the saved provider panel to blueprint editors. Choose the reader-visible option, `All Blueprint readers`, whose full label adds "approved metadata", only after approving the content for everyone who can read the blueprint. |
| Saved detail | Summary | Keeps object identity, operational states, counts and coverage with less monitoring detail. `Detailed` adds the affected monitoring names and member context. |
| Resource group scope | Direct members | `Include descendant groups` also includes resources within child groups when selecting a group. Duplicate memberships do not represent separate resources. |
| Maintenance context | Include maintenance windows | Adds available scheduled downtime context. Disable it to skip optional maintenance window reads. Alert downtime flags can still appear in Detailed snapshots. |
| Instance datapoints | Blank | Optionally enter up to three exact comma-separated datapoint names copied from the chosen DataSource instance. Metrics are fetched only for instance links and only when this field is populated. |

Existing connections keep their historical reader-visible detailed behaviour until an administrator chooses otherwise. Existing settings with no maintenance option do not enable additional maintenance reads.

Alert messages, acknowledgement comments, arbitrary resource properties and Collector configuration are not imported. Summary information still includes resource identity and operational metadata: it is not anonymous. Datapoint names and availability vary by DataSource; choose names meaningful to the interface or component rather than assuming every instance provides the same metrics. The [instance API](https://www.logicmonitor.com/support/getting-datasource-instance-details) and [data API](https://www.logicmonitor.com/support/getting-data) describe this resource hierarchy.

## Read the saved observation

The panel distinguishes active alert severity, collection availability and maintenance. Detailed snapshots also show acknowledgement and the affected DataSource, instance and datapoint. Acknowledgement means someone has acknowledged an alert; it does not mean the condition has recovered. Scheduled downtime can suppress notifications while monitoring continues. A Collector problem means the resource's current observations may be unavailable. None of these states should be read as a general guarantee of system health. See [LogicMonitor's scheduled downtime rules](https://www.logicmonitor.com/support/sdt-tab).

Alerting flags describe the object's local setting. The panel does not resolve every inherited group or DataSource alert-suppression rule; check the provider when deciding whether notifications should be sent.

Maintenance windows on an instance panel describe its parent device and can include other monitoring scopes; they are not all specific to the selected instance. A group panel reads schedules for the selected group, without individually retrieving schedules for every member device or child instance. Use each alert's downtime flag and the portal for precise maintenance scope.

Counts describe the active alerts and resources retrieved within the connection's permissions and selected scope. If pagination cannot be completed, the panel marks its coverage as partial; do not treat a lower bound as the full total. Unknown, missing or unreadable information is not zero. Last NetFlow receipt, if displayed, describes NetFlow specifically and does not establish the freshness of all monitored data.

Optional instance metrics request the past hour and show the latest 12 samples per selected datapoint, together with the requested and returned windows, sample interval and missing-data information. Summary mode uses generic metric labels; Detailed mode includes the selected datapoint names.

> [!NOTE]
> Metric samples are never labelled with a unit. The value column is headed "Value (unit unspecified)" and the Units row reads "Unit not supplied by LogicMonitor; untransformed provider values". Blueprintr shows the raw numbers without inferring a unit, converting the value or deriving a rate. Consult the DataSource definition in LogicMonitor to interpret the sample correctly.

Opening the stratum displays a saved snapshot and does not call LogicMonitor. Re-fetch with the circular-arrows icon on the linked row ("Re-fetch this integration's data"). After five minutes, the snapshot indicates that another refresh is needed. This is a freshness reminder, not automatic polling. Each metric has its own sample time; fetching a panel now does not make an older provider sample current.

Use the source link to continue investigating the selected device, group or instance in LogicMonitor. A link does not grant access: the provider still applies the signed-in user's own permissions. Extended graphs, alert messages, acknowledgement and configuration remain in the portal.

## Recover from failures and disconnect

A failed required read does not become an empty, healthy observation. A failed refresh keeps the previous snapshot and shows a warning. An optional section that cannot be retrieved is marked unavailable or partial. Check resource permissions and token expiry, then verify the connection again. For rate limits, wait before retrying; repeated browsing and refreshes consume the portal's API capacity.

Use `Rotate token`, then `Verify & replace`, to rotate a token. The replacement is verified before it replaces the working credential. `Suspend` stops search and refresh while saved snapshots stay readable; `Resume` restarts it. The broken-link icon on the linked row removes the current binding; delete the connection after its bindings have been removed. Moving to a different portal requires reviewing and relinking object identities; device IDs are not portable between companies.

## Sharing and retained copies

Provider data is fetched with the connection's credential. Readers are governed by the configured Blueprintr audience, not their individual LogicMonitor permissions. Approved reader-visible content can reach anonymous readers of a public blueprint, embeds, exports and configured search or AI features. Editor-only panels use Blueprintr's existing audience controls for those reader surfaces; editor exports and backups retain the source.

Changing a setting affects later successful fetches. Restricting the audience does not rewrite panels already saved: refresh each linked tab successfully, or unlink it, before treating existing LogicMonitor content as editor-only. It does not redact independent versions, templates, exports or copies already shared. Unlinking, suspending or revoking a token cannot recall those copies. Authored stratum names, link labels and notes remain your content and need a separate audience review.

## Validate before operational rollout

Automated tests exercise simulated provider responses; they do not establish that a particular LogicMonitor tenant grants the expected access. Before relying on this integration operationally, verify a least-privilege token, duplicate names, an exact instance, direct and descendant group membership, multi-page results, special-character searches and a permission-denied read in a representative portal. Confirm metric units and gaps, scheduled downtime, source links, freshness reminders and the published-reader audience. Check rate limits and any feature entitlements with that tenant. The integration does not import LogicMonitor topology or create monitoring configuration.

---

# Continuum Integrations: Auvik
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/auvik

> Network device context and alert history beside the component they explain.

Link an Auvik Network Management device to the stratum for a switch, firewall, server or other component in your diagram. The saved panel helps readers identify the device, understand its network context and review recent alert events. Open Auvik for its current dashboards, detailed investigation and operational actions. Continuum Link does not redraw the diagram.

This connection uses `Auvik Network Management`. It does not import Auvik SaaS Management applications, users, licences or security logs.

## Connect and select sites

1. You need an Enterprise licence, edit access to the blueprint and `continuum_integrations.manage` on the connection's organisation or team.
2. Create a dedicated Auvik service account with a custom API-only role and access to the intended sites. Give it read access to `API – Device info`, `API – Alerts` and `API – Tenants`. Auvik's built-in `Read Only` role does not grant these API permissions, and its built-in `API Access Only` role grants unrelated reads and tenant editing. Build a custom role with only the reads listed above. See [Auvik's service-account guidance](https://support.auvik.com/hc/en-us/articles/48529381648660-API-Access-Only-Role-and-Service-Account-Configuration-in-Auvik).
3. In Auvik, open `My Profile → Manage API Credentials` and generate the key. In Blueprintr, open `Settings → Continuum` on the organisation or team, go to `Operational integrations`, choose `New integration`, and select `Auvik` as the `Type`. Give the connection a `Name`, then enter `Region`, `Username` and the API key.
4. Review `Auvik snapshot audience`, `Saved detail` and the optional sections, then choose `Connect & verify`. To restrict the connection to named sites, select `Configure` on its row afterwards and open `Auvik site scope`. Clear `Include every accessible site`, choose `Load Auvik sites`, tick the sites, then choose `Verify & save settings`. Ticking a site does not save it on its own. `Exact site IDs` accepts up to 25 comma-separated leaf-site IDs instead. Changing the region or username requires saving and verifying again before the site list will load.
5. Save the blueprint and open the relevant stratum's `Continuum Link` controls from its `+ Add tab` menu. Search by device name, IP address, serial number or stable Auvik API ID and review the site, identity and matching evidence before linking. `Suggest integrations…` on a shape and `Scan for integrations` across the blueprint both offer candidates; selecting one is still an editor decision.

> [!IMPORTANT]
> `Region` is the cluster label in your Auvik API hostname, `auvikapi.<region>.my.auvik.com`, for example `us1` or `eu1`. It is not your customer domain and it is not a URL. Entering a URL is refused with "Enter the Auvik cluster region, such as us1; do not enter a URL."

`Include every accessible site` includes current and future sites accessible to the Auvik service account. Clear it and select exact sites to keep a connection focused on one customer or environment. The list uses Auvik's site labels or domain prefixes alongside stable IDs. Selecting a parent organisation is not a substitute for selecting its leaf sites. Device names and private IP addresses can repeat across sites: check the site and stable device ID before attaching a panel.

Verification checks inventory and alert access for each explicitly selected site. Optional capabilities are checked on one representative site; the result names that site. The first fetch and later refreshes check the actual linked device and available data, so a verified connection can still have unavailable optional observations on another device or site.

## Choose the saved information

| Setting | Default | What it changes |
| --- | --- | --- |
| Auvik snapshot audience | Blueprint editors | Keeps the imported panel visible to blueprint editors. Choose `All Blueprint readers` only after approving the information for everyone who can read the blueprint. Unlike Datadog, LogicMonitor and Rootly, Auvik's reader option carries no "approved metadata" suffix. |
| Saved detail | Summary | Keeps device and site identity, monitoring state, hardware, firmware and event counts. Detailed mode also permits internal IP addresses, serial numbers, network identities and alert names; review the resulting preview before sharing it. |
| Interfaces and connected peers | Off | Adds counts of disabled or impaired interfaces and history for up to two selected enabled interfaces with known peers. Detailed mode also shows up to 12 important interfaces with available peer and network relationships. Requires read access to `API – Interface info`. |
| Maintenance context | Off | Adds available running-configuration backup metadata and lifecycle context. Requires the corresponding device-detail and hardware-lifecycle reads. Configuration bodies are not imported. |
| Performance summary | Off | Adds device availability and outage plus interface utilisation and discard observations over the previous 24 complete UTC hours. The Auvik account must expose the statistics and the service account must be permitted to read them. |
| Alert history period | 7 days | Chooses a 1, 7 or 30-day history window. This does not define which alerts are currently active. |

Optional sections can be unavailable because of account permissions, discovery coverage or product availability. They do not require write access. Ask the Auvik administrator to grant the specific read permission or leave the section off; granting an administrative role is unnecessary.

## Read the panel in context

The device status is Auvik's observation at the fetch time. An online device can still have a fault, and a device marked unmanaged is not evidence of monitoring coverage. Missing information means unknown or unavailable, not healthy.

Alert history contains events that Auvik recorded during the selected window. Created, resolved, paused and unpaused events retain their meanings. A created event is not presented as proof that its alert is still active. Dismissal and dispatch are separate properties. Use the event's source link to check the current record in Auvik when using Detailed mode; Summary retains event counts and the device's dashboard link. The detailed timeline shows the most recent 20 retrieved events, and the scope states which interfaces were included. Detailed mode also caps the network membership table at 20 networks and the address list at 12, each with a coverage row stating what was omitted.

Interfaces distinguish whether a port is administratively enabled from its observed operational state. An administratively disabled port is different from a failed uplink. Peer and network relationships describe Auvik's discovered inventory; they do not establish that a route is reachable or that redundancy will work.

Maintenance information helps prepare a replacement or change. A backup timestamp does not prove that a restore will succeed. Lifecycle information can include Auvik's information provider, confidence and source links; review those sources before treating a predicted end-of-support date as a vendor commitment.

Performance observations cover the previous 24 complete UTC hours with hourly samples. The panel states its period and units; missing hours remain gaps, and an hourly average is not an instantaneous measurement or a service availability guarantee.

## Refresh and recover

Opening the tab shows its saved snapshot. Re-fetch with the circular-arrows icon on the linked row ("Re-fetch this integration's data"). After five minutes the snapshot is due for refresh; this is a reminder, not automatic polling. A failed refresh retains the previous snapshot with a warning. An unreadable or incomplete optional section is labelled rather than turned into zero alerts or a successful check.

If access fails, check the account's API role, selected sites and region. An Auvik account move can require a new region. Unlink every linked Auvik device before changing it: "Unlink existing Auvik devices before changing region, then review and link their identities in the new region." For a rate limit, wait before refreshing again.

Choose `Rotate token` on the connection's row, then `Verify & replace`, which verifies a replacement credential before it swaps. A replacement is refused when more than 50 linked Auvik identities need checking; move some links to another verified connection first. `Suspend` stops search and refresh while leaving snapshots readable, and the broken-link icon removes the current binding. Delete a connection after removing its bindings.

Site or credential changes must preserve access to existing links. If a new scope excludes a linked site, keep it selected or unlink that device first. Older links without a saved site identity need to be reviewed and linked again before their scope or credential identity can change.

## Sharing and retained copies

The panel is fetched with the service account's access. Readers do not need their own Auvik account to see an approved reader-visible snapshot. Opening a source link still requires their own Auvik access.

Editor-only panels use Blueprintr's existing audience controls for readers, embeds, viewer exports and search or AI indexing. Approved reader-visible content follows the blueprint's audience, including the public on a public blueprint. Editor exports and backups can retain the source information.

Settings apply to later fetches. Restricting the audience does not rewrite panels already saved: refresh each linked tab successfully, or unlink it, before treating existing Auvik content as editor-only. Settings do not retract previous exports, version history, templates or other independent copies, or redact authored titles and notes outside the managed panel. Revoking a key, suspending a connection or unlinking does not recall existing copies.

Before operational use, compare a known device and its history with your own Auvik account, confirm the selected sites and optional permissions, and check the reader view. Some Auvik API capabilities are documented as beta. Local tests do not establish your account's access or live data completeness.

---

# Continuum Integrations: ServiceNow CMDB
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-link/servicenow-cmdb

> The configuration item behind a shape, its relationships and its open work, beside the stratum that explains it.

Link a ServiceNow configuration item (CI) to the stratum for the component it records. The saved tab shows what the CMDB believes about that component: its class, lifecycle, environment, the groups that own and support it, when Discovery last saw it, how it relates to other CIs and, if you choose, the open incidents and changes recorded against it. Changing the record stays in ServiceNow.

Any record in `cmdb_ci` or a class that extends it can be linked: servers, network gear, application services, business applications. IP-address and network-adapter records are found too, but rank below the device with the same name.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and `continuum_integrations.manage` on the connection's organisation or team.
2. In ServiceNow, create a dedicated integration user. Give it the `cmdb_read` role, which reads every CMDB table. If the instance enables the REST API ACL, add `snc_platform_rest_api_access` as well. Tick `Web service access only` on the user, and keep it out of any policy that demands interactive multi-factor authentication: the connection signs in with the password on every call and cannot answer a prompt.
3. In Blueprintr, open `Settings → Continuum` on the organisation or team, go to `Operational integrations`, choose `New integration`, and select ServiceNow CMDB as the `Type`.
4. Enter the `Instance URL` (`https://acme.service-now.com`, reachable from the public internet), the `Username`, and the password, set the options below, and choose `Connect & verify`.

### Connection options

Each dropdown opens on `Use default`, which stores the first option.

| Field | Options | Effect |
| --- | --- | --- |
| `Snapshot audience` | Blueprint editors (recommended), All Blueprint readers | Who can read the saved tab. Readers includes anonymous readers, embeds and exports on a public blueprint |
| `Saved detail` | Detailed (default), Summary | Summary withholds the IP address, FQDN, MAC address, serial number, asset tag, location and description from the tab and from its saved data |
| `Open work` | Not imported (default), Open incidents and changes | Adds open incident and change counts for the CI, with the five newest task numbers and links to the filtered lists |

Verification reads one record from each table the connection will use: `cmdb_ci`, `cmdb_rel_ci`, and with open work switched on, `incident` and `change_request`. A table the user cannot read fails verification with its name and the role that grants it, for example "The ServiceNow account cannot read cmdb_rel_ci (HTTP 403 Forbidden). Grant cmdb_read, plus snc_platform_rest_api_access when the REST API ACL is enabled."

Open work needs `sn_incident_read` and `sn_change_read` from the ITSM Roles plugin, or `itil`. Those roles may count as a fulfiller licence on your instance; check with your account team before granting them.

On a domain-separated instance the user sees only its own domain, and so does the tab.

## Link a configuration item

Open the stratum and choose `Continuum Link`, then search by any of these.

| What you type | What happens |
| --- | --- |
| A name, FQDN, serial number or asset tag | Substring match on those four columns, up to 20 results |
| An IP address | Exact match on the CI's IP address column, plus a name match |
| A MAC address, with colons or hyphens | Exact match on the MAC address column in either form |
| A 32-character sys_id | The record itself |

Each result shows its class, IP address, location and lifecycle, so two records with the same name can be told apart, and its sys_id in the preview.

`Scan` and `Suggest` resolve hostnames, FQDNs, IP addresses, serial numbers and MAC addresses from the diagram. Identifiers of one kind are folded into a single query of up to 50, so a full site drawing costs a handful of reads.

## What the panel shows

| Section | Contents |
| --- | --- |
| Configuration item | Name, class, environment, classification, lifecycle stage, install status, operational status, model, manufacturer, and in Detailed mode the location, FQDN, IP address, MAC address, serial number, asset tag and description, then the record's last update in UTC |
| Ownership | Support group, managed-by group and change group. People are never imported |
| Discovery and attestation | When Discovery last and first saw the record and from which source, or "Never", and the attestation status and date |
| Open work | With open work switched on: open incident and change counts, then the five newest of each with priority, state and a link |
| Relationships | Up to 25 relationships as seen from this CI ("Depends on", "Used by", "Located in"), with the other CI's name and class, and the total when there are more |
| In ServiceNow | Links to the record's own form, the Dependency Views map and, with open work on, the filtered incident and change lists |

The headline reads the install status and operational status together, for example "Installed · Operational". ServiceNow keeps the two fields independently, so a record retired through install status is shown with a warning even while its operational status still says Operational. On order, in stock, in maintenance, repair, standby and ready states are shown as informational. The CSDM lifecycle stage appears as its own row.

Environment is the record's own environment field. Older records that only set the legacy "Used for" field show that value instead.

Dates come from the stored value and are labelled UTC. If an instance returns only display values, the date is shown as ServiceNow formatted it, without a zone label.

### Counting and its limits

Relationships stop at 25; the section title then reads "Relationships (25 of 61)". Open incidents and changes are read up to 25 each; the count states how many were retrieved when the total is higher.

## What is never imported

Person fields (owned by, managed by, assigned to, attested by), comments, work notes, incident and change descriptions, and any custom column. Only the named columns are requested, and the saved data is projected from them, so a column the instance returns anyway never reaches the blueprint.

## Audience

New connections save snapshots for blueprint editors only. Choose `All Blueprint readers` only when the class, ownership, relationships and, in Detailed mode, the addresses and serials are appropriate for everyone who can read the blueprint. Changing the audience applies to later refreshes and does not recall copies already shared, exported or answered by AI.

## Refreshing and recovery

Snapshots become due for refresh after one day, which is a reminder rather than automatic polling. A failed CI read keeps the previous snapshot and adds a warning. A relationship read or task read that fails marks the panel incomplete and says which table could not be read; the rest of the panel still saves. A rate limit answered by ServiceNow with `Retry-After` is reported with the number of seconds and is never retried in a loop.

---

# Continuum Integrations: Continuum Local
URL: https://docs.blueprintr.io/foliums/continuum-integrations/continuum-local

> The on-premise agent that lets Continuum Link read monitoring systems Blueprintr cannot reach.

Continuum Local is an agent you run inside your own network. It lets [Continuum Link](/foliums/continuum-integrations/continuum-link) read on-premise systems that are not exposed to the internet, and it can sweep your network for SNMP devices. The [Continuum Local guide](/foliums/blueprintr-user-guide/continuum/local-agent) in the Blueprintr user guide covers installing, configuring and running it.

It is the on-premise half of Continuum Link and sits behind the same gate: the organisation that owns the agent needs an Enterprise plan (a team's agent uses its parent organisation's plan), and you need `continuum_integrations.manage` on that organisation or team.

> [!IMPORTANT]
> Continuum Local is separate from [Continuum Cloud](/foliums/continuum-integrations/continuum-cloud). It discovers no cloud resources and never draws on a canvas. It serves connector panels on strata and runs network sweeps.

## What it serves

SolarWinds Orion, Zabbix, PRTG Network Monitor, Checkmk, Icinga 2, ManageEngine OpManager, WhatsUp Gold, NetBox, Infoblox and Veeam Backup & Replication. Each appears in the connector list and stays disabled until an agent that can serve it is online. The [connector reference](/foliums/continuum-integrations/continuum-link/connector-reference) lists what each one asks for and what its panel shows.

## How it connects

The agent dials out over HTTPS on port 443 to `blueprintr.io` and `agents.blueprintr.io`, directly or through a proxy. Nothing connects inward, so no inbound firewall rule is needed. It suits private and firewalled networks, not air-gapped ones: a host with no outbound path to Blueprintr cannot run it. [Network requirements](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements) lists every connection and port.

## Credentials

Blueprintr never stores a credential for an on-premise system. By default each credential is in the agent's `config.json`, or in an environment variable or file it refers to, and never leaves your network. If the agent's configuration allows it, credentials can also be sent from the Continuum Local panel instead: they pass through Blueprintr to the running agent, which must be connected to `agents.blueprintr.io` at the time, and are kept only on the agent.

The agent relays only requests it recognises as reads for each product, and only to the hosts its configuration lists. The [security model](/foliums/blueprintr-user-guide/continuum/local-agent/security) says what the agent enforces, and what Blueprintr stores, who can see it and how long it is kept.

## Getting and registering it

Download the agent from the [Continuum Local download page](https://blueprintr.io/download/continuum-local) while signed in to an account on an Enterprise plan. It comes as Debian and RHEL packages, a Windows installer, a container image, a Helm chart and a single file for a host with Node.js 24, and every release is signed.

Register it from **Settings → Continuum → Continuum Local** on the organisation or team. Choose **Add an agent**, copy the enrolment token, which is shown once and expires after 24 hours, and put it in the agent's configuration. [Installing Continuum Local](/foliums/blueprintr-user-guide/continuum/local-agent/install) has the steps for each platform.

## Network sweeps

With a `discovery` block in its configuration, an agent sweeps the address ranges you allow for SNMP devices, over SNMP v1, v2c or v3. Start or schedule a sweep from **Network sweeps** below the Continuum Local panel. Blueprintr can narrow a sweep to some of the agent's ranges but never widen it, and the SNMP credentials stay on the agent. Blueprintr keeps sweep results for 90 days, and each agent's latest complete sweep until a newer one completes. [Network discovery](/foliums/blueprintr-user-guide/continuum/local-agent/network-discovery) says what a sweep reads.

## The full guide

> [!TILES 3]
>
> === [Installing](/foliums/blueprintr-user-guide/continuum/local-agent/install)
>
> Prerequisites, sizing, each platform, and enrolling the agent.
>
> === [Network requirements](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements)
>
> Outbound connections, ports, proxies and TLS inspection.
>
> === [Configuration reference](/foliums/blueprintr-user-guide/continuum/local-agent/configuration)
>
> Every setting in `config.json`, secret references and the check command.
>
> === [Security model](/foliums/blueprintr-user-guide/continuum/local-agent/security)
>
> What the agent enforces, and what Blueprintr stores, who sees it and for how long.
>
> === [Network discovery](/foliums/blueprintr-user-guide/continuum/local-agent/network-discovery)
>
> What an SNMP sweep reads, its limits, and running and reviewing sweeps.
>
> === [Releases and verification](/foliums/blueprintr-user-guide/continuum/local-agent/releases)
>
> Versions, signatures, SBOMs and which releases are supported.
>
> === [Upgrading and removing](/foliums/blueprintr-user-guide/continuum/local-agent/upgrade-and-uninstall)
>
> Upgrades, rollbacks, credential rotation and uninstalling.
>
> === [Troubleshooting](/foliums/blueprintr-user-guide/continuum/local-agent/troubleshooting)
>
> Logs, error codes and common failures.
>
> === [Questions and limitations](/foliums/blueprintr-user-guide/continuum/local-agent/faq)
>
> Air-gapped networks, redundancy, a lapsed plan and other limits.

---

# Blueprintr User Guide: Welcome
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide

> Blueprintr publishes documentation with a diagram at the centre of it, and keeps the two attached.

Blueprintr publishes documentation built around a diagram rather than beside
one. You draw the system, attach the detail to the parts of the drawing it
describes, and publish the result as one thing.

> [!TILES 3]
>
> === [Publish in ten minutes](/foliums/blueprintr-user-guide/start/publish-in-ten-minutes)
>
> Sign in, draw something, publish it, in one pass.
>
> === [The vocabulary](/foliums/blueprintr-user-guide/start/vocabulary)
>
> Blueprint, stratum, vellum, folium, podium, atrium: what each one is.
>
> === [Where content lives](/foliums/blueprintr-user-guide/start/where-content-lives)
>
> Personal, team or organisation, chosen at creation.

## Pick a starting point

| You want to | Go to |
| --- | --- |
| Draw a diagram and publish it | [Your first blueprint](/foliums/blueprintr-user-guide/start/your-first-blueprint) |
| Attach detail to parts of a diagram | [Strata](/foliums/blueprintr-user-guide/strata) |
| Build a documentation site like this one | [Documentation sites](/foliums/blueprintr-user-guide/foliums) |
| Present a diagram to a room | [Podium](/foliums/blueprintr-user-guide/sharing/podium) |
| Put a diagram in someone else's page | [Embedding](/foliums/blueprintr-user-guide/sharing/embedding-blueprints) |
| Set up a workspace for a team | [Setting up an organisation](/foliums/blueprintr-user-guide/teams/setting-up-an-organisation) |
| Keep a cloud diagram matching live infrastructure | [Continuum](/foliums/blueprintr-user-guide/continuum) |
| Drive Blueprintr from code or an agent | [Developers](/foliums/blueprintr-user-guide/developers) |

## What the pieces are

A **blueprint** is the published unit: one or more diagram tabs, the prose
around them, and the files they reference. A **stratum** is detail bound to a
single shape, opened by clicking that shape. **Vellum** is the diagram editor.
A **folium** is a multi-page documentation site. This guide is one.

---

# Blueprintr User Guide: Start
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/start

> From an empty account to a published page, with the vocabulary you need on the way.

Read the first two pages if you are in a hurry.

> [!TILES 2]
>
> === [Publish in ten minutes](/foliums/blueprintr-user-guide/start/publish-in-ten-minutes)
>
> The whole loop, once.
>
> === [The vocabulary](/foliums/blueprintr-user-guide/start/vocabulary)
>
> Seven words that everything else is built from.
>
> === [Your first blueprint](/foliums/blueprintr-user-guide/start/your-first-blueprint)
>
> The three-step editor in detail.
>
> === [Where content lives](/foliums/blueprintr-user-guide/start/where-content-lives)
>
> Personal, team or organisation, and how to move something later.
>
> === [The dashboard](/foliums/blueprintr-user-guide/start/dashboard)
>
> What each rail item is for.

---

# Blueprintr User Guide: Publish in ten minutes
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/start/publish-in-ten-minutes

> Sign in, draw something, publish it. The whole loop once, from account to live page.

One complete pass through Blueprintr, from registration to a published page.

Walk it as slides first. Five screens, with the control under discussion
ringed on each:

![blueprint:josh/publishing-your-first-blueprint](https://blueprintr.io/embed/josh/publishing-your-first-blueprint?exclude=cmtp5f2me0002cp57fc6rmk9m&hideTabBar=1#h=620)

Then the same loop in writing:

> [!STEPS]
>
> === Sign in and finish your profile
>
> Register at [blueprintr.io](https://blueprintr.io/register) or sign in with
> an existing account. New accounts are sent to **Complete your profile**
> first: a handle and a few interests. The handle becomes the first segment
> of every URL you publish, so pick one you can live with.
>
> === Start a blueprint
>
> From the dashboard, choose **Create blueprint**. You land in step 1,
> **Content**.
>
> === Give it a title and draw
>
> Type a title, then draw on the canvas. The first tab of a blueprint must be
> a diagram. Vellum is the default editor; [other engines](/foliums/blueprintr-user-guide/vellum/draw-io-excalidraw-and-mermaid) are available from
> the engine menu.
>
> === Attach detail to a shape
>
> Right-click any shape and choose **Add Stratum…**, then write a couple of
> sentences. Do it on the first pass rather than saving it for later.
>
> === Move to Resources & Strata
>
> Step 2 collects everything alongside the diagram: strata, further diagrams,
> and uploads. It can be skipped entirely on a first blueprint.
>
> === Publish
>
> Step 3 is **Publish**: tags, visibility, and pre-flight checks. Choose
> **Public** if you want a shareable link, **Private** to keep it to yourself.
> Fix anything the pre-flight flags, then publish.

Your blueprint is now at `blueprintr.io/<your-handle>/<slug>`.

## What to do next

> [!TILES 3]
>
> === [Your first blueprint](/foliums/blueprintr-user-guide/start/your-first-blueprint)
>
> The same three steps, in detail, with the parts this page skipped.
>
> === [Strata](/foliums/blueprintr-user-guide/strata)
>
> The layered-detail model in full.
>
> === [Embedding](/foliums/blueprintr-user-guide/sharing/embedding-blueprints)
>
> Put what you just published inside another page.

---

# Blueprintr User Guide: Vocabulary
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/start/vocabulary

> Blueprint, stratum, vellum, folium, podium, atrium and portfolio are the seven words the rest of the product is built from.


Blueprintr uses a small number of made-up words. They are all names for
ordinary things.

![blueprint:josh/how-blueprintr-fits-together](https://blueprintr.io/embed/josh/how-blueprintr-fits-together#h=540)

| Word | What it is |
| --- | --- |
| **Blueprint** | The published unit. One or more tabs, at least one of which is a diagram, plus the prose and files around it. |
| **Vellum** | The diagram editor. Also the default engine for any new diagram. |
| **Stratum** | Detail bound to one shape on a diagram. Click the shape, the detail opens. |
| **Folium** | A multi-page documentation site with a nav tree and an automatic contents list. This guide is a folium. |
| **Podium** | A diagram presented as slides. |
| **Atrium** | An organisation's searchable homepage: its blueprints, foliums and people in one place. |
| **Portfolio** | A folder for related content. Portfolios hold blueprints, diagrams, links, notes, and other portfolios. |

## How they relate

You draw in **Vellum**. The drawing becomes a diagram tab inside a
**blueprint**. Shapes on that diagram carry **strata**. The blueprint is filed
in a **portfolio** and published once. The same content is then readable on
your profile, in an **Atrium**, embedded in a **folium**, or presented as a
**podium**.

> [!NOTE]
> A diagram does not have to be a blueprint. Standalone diagrams sit under
> **Dashboard → Diagrams** and can be embedded anywhere a blueprint can.

## Compendium and Continuum

**Compendium** is the [template library](/foliums/blueprintr-user-guide/blueprints/templates-and-the-compendium).
[**Continuum**](/foliums/blueprintr-user-guide/continuum) connects a diagram to a
live cloud account so the drawing can be checked against what exists.

---

# Blueprintr User Guide: Your first blueprint
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/start/your-first-blueprint

> What each of the three editor steps is for, and what it will not let you skip.

The blueprint editor has three steps. Move between them in any order; only
publishing is gated.

| Step                  | What it is for                                            |
| --------------------- | --------------------------------------------------------- |
| 1. Content            | The title, and the tabs. The first tab must be a diagram. |
| 2. Resources & Strata | Strata, further diagrams, and uploaded files.             |
| 3. Publish            | Tags, visibility, and pre-flight checks.                  |

## Step 1: Content

A blueprint is a set of **tabs**. The first is always a diagram; after that,
add Rich Text tabs for prose, Raw tabs for code or config, and further diagram
tabs.

Use tabs for separate views of the same subject: a logical view and a physical
view, or one per environment. Do not use them as chapters of an essay; that is
what [strata](/foliums/blueprintr-user-guide/strata) and [foliums](/foliums/blueprintr-user-guide/foliums) are for.

> \[!TIP]
> Clicking a shape while in step 1 offers to add a stratum to it. You do not
> have to wait for step 2.

## Step 2: Resources & Strata

Everything that sits alongside the diagram:

> \[!FIELDS]
>
> > \[!FIELD Strata|per shape|optional]
> >
> > Detail bound to shapes, on any diagram in the blueprint, including
> > diagrams embedded inside rich text.
>
> > \[!FIELD Diagrams|any engine|optional]
> >
> > Further diagrams that are not tabs, referenced from prose or from a
> > stratum.
>
> > \[!FIELD Files|upload|optional]
> >
> > Images and attachments, organised in folders.

## Step 3: Publish

**Tags** are suggested from your content and can be edited. They drive
discovery and the related-content rail.

**Visibility** is one of three values:

| Value    | Who can read it                              |
| -------- | -------------------------------------------- |
| Public   | Anyone, and it can be indexed                |
| Unlisted | Anyone with the link                         |
| Private  | You, and anyone the blueprint is shared with |

**Pre-flight checks** run last. They catch the things that make a published
blueprint look unfinished: an empty canvas, a tab with no content, a missing
title. Publishing is blocked until they pass.

> \[!NOTE]
> Publishing sets a version. Later edits are drafts against that version, and
> readers keep seeing the published one until you publish again. See
> [versions and history](/foliums/blueprintr-user-guide/blueprints/versions-and-history).

---

# Blueprintr User Guide: Where content lives
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/start/where-content-lives

> Every blueprint belongs to you, a team, or an organisation. Choosing at creation time saves a move later.

Everything you create is owned by exactly one of three things: **you**, a
**team**, or an **organisation**. The choice sets who can edit it, where it
appears, and what its published URL looks like.

| Owner | Edited by | Published at |
| --- | --- | --- |
| You | You, plus anyone you share with | `blueprintr.io/<your-handle>/<slug>` |
| A team | The team's members, subject to their role | The team's page inside its organisation |
| An organisation | Members with the right role | The organisation's Atrium, and its subdomain if it has one |

## Choosing at creation

The wizard's **Publish to** selector sets the owner. It is seeded from
whichever workspace you were looking at when you started.

> [!IMPORTANT]
> Ownership is not the same as visibility. An organisation blueprint can still
> be public, and a personal blueprint can still be private. See
> [the visibility model](/foliums/blueprintr-user-guide/sharing/visibility-model).

![blueprint:josh/three-independent-choices](https://blueprintr.io/embed/josh/three-independent-choices#h=640)

## Moving something later

Reassigning an owner changes the published URL. Filing the same blueprint in a
different [portfolio](/foliums/blueprintr-user-guide/organise/portfolios-and-folders) changes neither ownership nor the
URL.

> [!TIP]
> If you are on your own and unsure, publish to yourself. A personal blueprint
> can be moved into an organisation later; the reverse is harder because
> permissions and audit history come with it.

---

# Blueprintr User Guide: Dashboard
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/start/dashboard

> What each item in the left rail is for, and which workspace you are looking at.


The dashboard is scoped to **one workspace at a time**. The switcher at the
top of the left rail decides whether you are looking at your own content, a
team's, or an organisation's. It also seeds the **Publish to** selector when
you start something new.

![blueprint:josh/finding-your-way-around-the-dashboard](https://blueprintr.io/embed/josh/finding-your-way-around-the-dashboard?exclude=cmtpwcfrt000t11r4bbzvglpj&hideTabBar=1#h=620)

If you cannot find a blueprint, check that switcher. It may belong to a
different workspace.

![The workspace switcher at the foot of the rail, showing Personal / Personal workspace](/api/folium-assets/cmtozqm4p0005ykw4e7kxl8c0/raw)

## The rail

| Item | What is there |
| --- | --- |
| Dashboard | Recent and pinned content for the current workspace |
| Blueprints | Every blueprint you can see in this workspace |
| Vellum diagrams | Standalone diagrams, not attached to a blueprint |
| Foliums | Documentation sites |
| Portfolios | Your folders. **Main** is created automatically and cannot be deleted |
| Bookmarks | Things you saved from anywhere on the platform |
| Compendium | The template library |
| Analytics | Views and engagement across the workspace |
| Libraries | Icon packs and stencils available to your diagrams |
| Licensing & Billing | Plan, seats, credits and invoices |
| Settings | Account, security, and workspace preferences |

**Customize sidebar** at the foot of the rail decides which of these are
pinned, so your own rail may show fewer of them.

## The three buttons

![Create blueprint, Draw with Vellum and Import, stacked at the foot of the rail](/api/folium-assets/cmtozqlty0003ykw474bepv2l/raw)

**Create blueprint** opens the three-step editor. **Draw with Vellum** creates
a standalone diagram with no blueprint around it. **Import** opens the
[import wizard](/foliums/blueprintr-user-guide/organise/importing-content) for content coming from Confluence, Notion,
SharePoint, or a set of files.

> [!TIP]
> Start from a team or organisation workspace and anything you create there is
> owned by it. See [where content lives](/foliums/blueprintr-user-guide/start/where-content-lives).

---

# Blueprintr User Guide: Blueprints
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints

> Tabs, strata, files and metadata, what a blueprint is made of, and which parts are required.


A blueprint is one published thing made of several parts. Only the first is
mandatory.

| Part | Required | What it is |
| --- | --- | --- |
| Diagram tab | Yes, at least one | The drawing. Must be the first tab. |
| Further tabs | No | More diagrams, prose, code, or an embedded folium or video. |
| Strata | No | Detail bound to individual shapes. |
| Files | No | Uploads, in folders. |
| Tags | No | Discovery and the related-content rail. |
| Version | Set on publish | What readers see while you edit the next draft. |

## Why a diagram is mandatory

A blueprint without a diagram is a document, and there are better tools for
documents. Requiring one in first position means every blueprint opens with a
picture, and every reader gets orientation before prose.

## Tabs

Tabs are separate views of the same subject, not chapters: a logical view and a
physical view, one per environment, or the architecture and the sequence.

Six kinds are available:

| Kind | Holds |
| --- | --- |
| Diagram | A canvas, in any supported engine |
| Rich text | Markdown with the full component library |
| Raw | Code or config, line-numbered |
| Folium | A live, browsable documentation site |
| Video | A YouTube, Vimeo, Loom or direct video URL |
| Source embed | Content pulled from a connected Confluence, Notion or SharePoint |

> [!NOTE]
> Continuum-managed components exist too, but they are written by
> [Continuum](/foliums/blueprintr-user-guide/continuum) rather than by hand.

> [!TILES 3]
>
> === [The editor](/foliums/blueprintr-user-guide/blueprints/editor)
>
> The three steps, and what each gates.
>
> === [Diagram tabs](/foliums/blueprintr-user-guide/blueprints/diagram-tabs)
>
> Adding, ordering and naming tabs.
>
> === [Publishing](/foliums/blueprintr-user-guide/blueprints/publishing-and-visibility)
>
> Visibility, pre-flight checks and versions.

---

# Blueprintr User Guide: Editor
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/editor

> Content, Resources and Strata, and Publish. The editor's three steps, and the checks that gate publishing.


Open the editor with **Create blueprint** on the dashboard, or by editing an
existing blueprint. The three steps can be visited in any order; only
publishing is gated.

![blueprint:josh/the-editor-s-three-steps](https://blueprintr.io/embed/josh/the-editor-s-three-steps?exclude=cmtpw850a001klduybth3p0r1&hideTabBar=1#h=620)

## 1. Content

Title and tabs. The first tab must be a diagram.

The canvas fills most of the step. The engine menu switches between Vellum,
draw.io, Excalidraw and Mermaid; Vellum is the default unless you have changed
it in **Settings → General**.

Right-clicking a shape offers **Add Stratum…** here, so detail can be written
before the diagram is finished.

## 2. Resources & Strata

Everything alongside the diagram: strata, further diagrams that are not tabs,
and uploaded files organised into folders.

Skippable on a first pass.

## 3. Publish

> [!STEPS]
>
> === Review the suggested tags
>
> Generated from your content. Correct them: they drive discovery and the
> related-content rail.
>
> === Set visibility
>
> [Public, unlisted, or private](/foliums/blueprintr-user-guide/blueprints/publishing-and-visibility).
>
> === Clear the pre-flight checks
>
> Empty canvases, empty tabs and missing titles are blocked here rather than
> shipped. Each item in the list links to the thing to fix.
>
> === Publish
>
> Sets a version. Readers see that version until you publish again.

> [!TIP]
> **Preview** shows the reader's view without publishing, including strata and
> tab chrome. Use it before the first publish rather than after.

---

# Blueprintr User Guide: Content blocks
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/content-blocks

> The component library available in every rich text surface, including callouts, steps, tabs, accordions, tiles and fields.


Rich text in Blueprintr is markdown plus a component library. The same
components work in a blueprint's Rich Text tabs, in a stratum's Rich tab, and
on every folium page, including this one.

Every component is written as a blockquote whose first line is a marker.
That format survives the visual editor, and degrades to a readable quote in
any plain markdown renderer.

## Callouts

```markdown
> [!NOTE]
> Ordinary supporting detail.
```

Available kinds: `NOTE`, `TIP`, `IMPORTANT`, `INFO`, `FAQ`, `TLDR`, `QUOTE`.

> [!TIP]
> A callout can link to a stratum: `> [!NOTE|stratum:abc123] Title`.

## Procedures

```markdown
> [!STEPS]
>
> === Install the CLI
>
> Run the installer.
>
> === Authenticate
>
> Then sign in.
```

Steps are numbered automatically. A plain ordered list inside `[!STEPS]` works
too.

## Panels and grids

`=== Label` on its own line separates panels in every multi-panel component.

| Marker | Renders |
| --- | --- |
| `[!TABS]` | Tabbed panels |
| `[!CODETABS]` | Tabbed code blocks, one fence per panel |
| `[!ACCORDIONS]` | Collapsible `<details>`, no JavaScript |
| `[!COLUMNS n]` | An n-column responsive grid |
| `[!TILES n]` | A tile grid, for navigation |
| `[!CARDS]` | A card grid built from a markdown list |
| `[!PANEL] Title` | An aside |

## API and reference

```markdown
> [!FIELDS]
>
> > [!FIELD userId|string|required]
> >
> > The caller's user id.
>
> > [!RESPONSE createdAt|datetime]
> >
> > When the record was written.
```

## Inline pieces

| Marker | Renders |
| --- | --- |
| `[!BADGE green] Stable` | A small label. Colours: gray, blue, green, amber, red, purple, teal, pink |
| `[!ICON rocket] Ship it` | A Lucide glyph, optionally labelled |
| `[!TOOLTIP hint text]` | A term with a hover and focus hint |
| `[!BANNER warning]` | A page-level banner. Types: info, warning, success, error |
| `[!TREE]` | A file tree, from a nested markdown list |
| `[!UPDATE v2.1.0\|2026-09-05]` | A dated changelog entry |
| `[!FRAME]` | A decorative frame |
| `[!DETAILS] Summary` | One collapsible block. `[!DETAILS\|open]` starts expanded |

## Audience splitting

```markdown
> [!VISIBILITY agents]
>
> Notes for an AI agent reading this page.
```

Content marked `agents` is removed before the HTML reaches a human reader, and
content marked `humans` is removed for an agent. Use it for machine-readable
hints you do not want on the page.

> [!IMPORTANT]
> A malformed marker degrades to an ordinary blockquote rather than being
> dropped. If a component renders as a plain quote, the marker line is wrong.

## Embeds

| Syntax | Embeds |
| --- | --- |
| `![diagram:vellum](url)` | A diagram from an uploaded source |
| `![blueprint:handle/slug](embed-url)` | Another blueprint |
| `![video](url)` | A video |

Diagram embeds can be resized by dragging their corners; the size is written
back into the markdown.

---

# Blueprintr User Guide: Diagram tabs
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/diagram-tabs

> Adding, naming and ordering the tabs across the top of a blueprint.

Tabs run across the top of a published blueprint and are the reader's main
navigation. The first is always a diagram.

## Adding

**Add tab** in step 1 offers the six kinds. The choice is fixed once content
exists in the tab.

## Naming

Tab names are the labels on the strip. Short nouns work: *Logical*, *Physical*,
*Runtime*, *Data*. Avoid restating the blueprint title in every tab.

> [!TIP]
> A tab strip is easy to miss. If a later tab holds something essential, say
> so in the first tab's prose.

## Ordering

Drag to reorder. The first tab must remain a diagram: the editor will not let
you drag a prose tab into first position.

## Engines

Each diagram tab has its own engine, and a blueprint can mix them: a Vellum
context diagram, a Mermaid sequence diagram, and an imported draw.io network
diagram in one document.
[draw.io, Excalidraw and Mermaid](/foliums/blueprintr-user-guide/vellum/draw-io-excalidraw-and-mermaid)
covers the non-Vellum engines.

## Limits

There is a hard ceiling on tabs per blueprint. If you are close to it, split
the content into several blueprints in a
[portfolio](/foliums/blueprintr-user-guide/organise/portfolios-and-folders), or move
it into a [folium](/foliums/blueprintr-user-guide/foliums).

---

# Blueprintr User Guide: Discussion and change requests
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/discussion-and-change-requests

> Comment threads on a blueprint, and the proposal flow for changing one you cannot edit.

A published blueprint has a place to talk about it, and a way to propose
changing it.

## Discussion

The **Discussion** tab holds topics. Anyone who can read the blueprint can
open one; replies thread underneath. It is for questions and context: "why is
this queue here", "is this still true after the migration".

Discussion never changes the blueprint.

## Change requests

A change request proposes an edit to a blueprint you do not have edit rights
on. It is the analogue of opening a pull request against someone else's
repository.

![blueprint:josh/change-request-lifecycle](https://blueprintr.io/embed/josh/change-request-lifecycle#h=520)

| Status | Meaning |
| --- | --- |
| Open | Submitted, awaiting a decision |
| Approved | Accepted, not yet applied |
| Merged | Applied to the blueprint |
| Rejected | Declined |
| Withdrawn | Retracted by whoever raised it |

> [!NOTE]
> The AI docs agent files a change request rather than writing to a page
> directly. A person still has to merge it.

## Reviews

Organisations can require review before publishing. Where that is configured, a
publish becomes a submission and the blueprint waits in
[Reviews](/foliums/blueprintr-user-guide/teams/reviews-and-approvals) until someone with the
right role approves it.

---

# Blueprintr User Guide: Files and folders
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/files-and-folders

> Uploads that belong to a blueprint, the size ceilings and storage quotas, and how an over-quota account recovers.

Step 2 of the editor holds a column view for everything uploaded alongside the
blueprint: images used in prose, attachments readers can download, and diagram
sources.

## Folders

Files have a folder path rather than sitting in actual directories, so
reorganising never breaks a reference. Create a folder, drag files into it,
rename freely.

## Referencing a file

An uploaded image is inserted into rich text as an ordinary markdown image;
other files become links. Both keep resolving after a move, a rename, and a
publish.

A file's URL is keyed on the **file's** id, not the blueprint's, because
publishing reparents a draft's files onto the published blueprint and deletes
the draft row. A blueprint id baked into a link would dangle after one publish.
The URL also re-resolves storage on every request, so a reference that outlives
a signed URL's expiry still works.

## Visibility

> [!IMPORTANT]
> Files inherit the blueprint's access, checked on every read against the
> blueprint that owns the file *now*, never against one supplied by the caller.
> A file on a private blueprint is not readable by an anonymous visitor even
> with a direct URL, and a password gate covers the files too.
>
> Unlisted is not secret. Anyone with the link has the attachments.

## Ceilings

| | |
| --- | ---: |
| One uploaded file | 20 MB |
| One diagram document, including its thumbnail | 5 MB |

The 5 MB document cap exists because the request body ceiling above it is
6 MB. A document that passed would fail on the way out.

## Quotas

Storage is counted per owner, not per blueprint:

| Owner | Quota |
| --- | ---: |
| Personal, free | 500 MB |
| Personal, premium | 5 GB |
| Team | 20 GB |
| Organisation | 20 GB |
| Organisation, enterprise | 100 GB |

The total counts diagram documents and their thumbnails, externalised diagram
images, attachments, blueprint asset files and custom icon packs. A draft and
its published sibling share the same stored objects, so a published blueprint
is not charged twice.

It does not yet count inline markdown, version snapshots, templates, folium
assets, podium assets, avatars and covers. The figure therefore runs below
actual usage.

> [!TIP]
> A write that reduces your total is never rejected, whatever your quota says,
> because deleting is how an over-quota account recovers. If you are blocked,
> delete something and carry on. The limit does not need raising first.

Both figures are shown on
[billing and usage](/foliums/blueprintr-user-guide/account/billing-and-usage).

---

# Blueprintr User Guide: Publishing and visibility
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/publishing-and-visibility

> Draft and published states, the three visibility values, and what the pre-flight checks block.

**Status** and **Visibility** are independent properties. Status is whether the
blueprint has ever been published. Visibility is who may read it once it has
been.

![blueprint:josh/publishing-states](https://blueprintr.io/embed/josh/publishing-states#h=500)

## Status

A new blueprint is a **draft**: only you and anyone you share it with can see
it, whatever its visibility says. Publishing makes the current content the
live version. Editing afterwards creates a new draft against that version, so
readers keep seeing the last published state until you publish again.

## Visibility

| Value | Who can read it | Indexed |
| --- | --- | --- |
| Public | Anyone | Yes |
| Unlisted | Anyone with the link | No |
| Private | You, and anyone it is shared with | No |

> [!IMPORTANT]
> An unlisted URL is unguessable, not protected. Anything that would matter if
> it leaked should be private.

## Pre-flight checks

Publishing is blocked until these pass:

- an empty diagram canvas
- a tab with no content
- a missing title
- a rich tab containing only whitespace

Each finding links to the thing to fix.

## Ownership and classification

**Publish to** sets the owner: you, a team, or an organisation, as described in
[where content lives](/foliums/blueprintr-user-guide/start/where-content-lives).

Organisations can apply a
[**classification**](/foliums/blueprintr-user-guide/teams/policies) that
constrains what visibility a blueprint is allowed to have. Where a
classification is set, you cannot publish above the ceiling it defines.

---

# Blueprintr User Guide: Versions and history
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/versions-and-history

> Every publish snapshots the blueprint, and restoring a snapshot replaces the current content.

Publishing writes a version. The **History** tab lists them, newest first.

> [!IMPORTANT]
> Version history is a **Teams** feature. Without a Teams-licensed
> organisation the tab explains that rather than opening. Publishing still
> snapshots, but the snapshots cannot be browsed or restored.

## What a version holds

A complete frozen copy of the blueprint at publish time: tabs, diagram sources,
strata and files. It is not a diff, so an old version renders as it did rather
than being reconstructed.

## Comparing

The panel offers four views of a version:

| | |
| --- | --- |
| Snapshot preview | The version rendered faithfully, as it was |
| Diff | What changed against the previous version |
| Compare with this version | Pick any earlier version as the baseline instead |
| Raw JSON | The snapshot itself, when the rendered view is not enough |

Diffing against the previous version answers "what did that publish change".
**Compare with this version** sets an older baseline and answers "what has
changed since the release we shipped against".

## Restoring

> [!IMPORTANT]
> Restore **replaces the current content**. It deletes and recreates the
> blueprint's tabs, strata and files from the snapshot, and anything you have
> not published since is gone. Confirming takes two clicks, and the second one
> says so.

History is append-only, so the state you replaced is itself still a version.
A restore you regret is undone by restoring the one before it.

## Pinning

An [embed](/foliums/blueprintr-user-guide/sharing/embedding-blueprints) can be pinned to
a version rather than tracking the latest. A blueprint quoted in a report then
stays as it was on the day it was quoted.

---

# Blueprintr User Guide: Analytics
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/analytics

> Where a blueprint's readers came from, how on-platform arrivals are attributed, and who can open the panel.

Analytics is reported at two scopes from the same data: the **Analytics** tab
on the blueprint itself, and **Dashboard → Analytics**, across everything you
can see in the current workspace.

## Who can see it

Analytics is owner data, and access is narrower than for the tabs beside it:
the author, anyone who can edit the blueprint (team and org managers, plus
explicit ACL-edit), or a moderator. A reader who can open the blueprint cannot
open its analytics.

> [!IMPORTANT]
> It is a **premium** feature, and the plan that counts is the **author's**,
> not yours. On an org-owned blueprint the author is still the creator, so a
> team manager on a paid plan can find analytics unavailable because the person
> who wrote it is not.

## What is counted

| | |
| --- | --- |
| Views | All-time and over the selected window |
| Unique visitors | Distinct sessions, not identified people |
| Views over time | The trend across the selected window |
| Referrer domains | Where off-platform traffic arrived from |
| Agent traffic | Crawlers and AI agents, separated from humans |
| Engagement | Including the helpful / not-helpful tally |

Counts only. No reader is identified: the session is hashed, and nothing in the
panel resolves to a person.

## Traffic sources

On-platform arrivals are attributed to the surface that produced them, in the
platform's own vocabulary:

| Source | Reader arrived from |
| --- | --- |
| Direct link | A URL someone gave them |
| Explore | Browsing Explore |
| Explore (featured pin) | A featured position in Explore |
| For-you feed | The personalised feed |
| Fresh feed | The recency feed |
| Following | Following you or your organisation |
| Tag page | A tag they were browsing |
| Author profile | Your profile page |
| Bookmarks | Their own bookmarks |
| Comments | A comment thread |
| Resume reading | Picking a blueprint back up |
| Direct / other | Everything unattributable |

The breakdown shows whether a blueprint is found because people go looking for
it, or only because you sent them the link.

## Embeds

Views through an [embed](/foliums/blueprintr-user-guide/sharing/embedding-blueprints) are
counted and attributed to the embedding page.

> [!NOTE]
> Anonymous readers on the embed surface leave nothing on their device: no
> cookie is written there. Counts are aggregate rather than per-person, and no
> setting changes that.

---

# Blueprintr User Guide: Tags and discovery
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/tags-and-discovery

> Four broad categories, a curated middle layer of sub-interests, and the freeform tags you attach at publish time.

Tags are set on the Publish step. They drive search ranking, the related-content
rail, and the public [tag pages](https://blueprintr.io/tags).

## The three layers

Discovery runs on a three-level taxonomy.

> [!FIELDS]
>
> > [!FIELD Broad category|four, fixed|top]
> >
> > Technical, Data & AI, Product & Design, and Game Design.
>
> > [!FIELD Sub-interest|32, curated|middle]
> >
> > Six to eleven per broad category, and the level a reader chooses between.
> > Grows slowly and additively.
>
> > [!FIELD Tag|freeform|leaf]
> >
> > What you attach to a blueprint. Tags map upward into sub-interests.

| Broad category | Covers |
| --- | --- |
| Technical | Architecture, cloud, networking, security, DevOps, APIs, embedded, hardware, robotics |
| Data & AI | Pipelines, analytics, ML systems, generative AI, agents, MLOps, data modelling |
| Product & Design | User flows, IA, wireframes, service blueprints, product strategy, UX research, design systems |
| Game Design | Mechanics, level design, branching narrative, economies, AI behaviour, multiplayer |

A reader picks broad categories and sub-interests, and your tags are matched
against them. The match fills a signed-in reader's dashboard, reaching people
who never searched for the blueprint.

## Suggestions

At publish time a classifier proposes tags from your content, using embeddings
and a language model, each with a confidence score. You accept the right ones
and delete the rest.

Every attachment records how it got there:

| Provenance | Means |
| --- | --- |
| `manual` | You typed or picked it. No confidence score |
| `llm-accepted` | Proposed by the classifier, accepted by you |
| `llm-suggested` | Proposed, not yet confirmed. A review candidate rather than a live tag |

An unaccepted suggestion is not attached.

> [!IMPORTANT]
> A wrong tag is worse than a missing one. It puts your blueprint in front of
> people looking for something else, who bounce, lowering its ranking for the
> people who did want it. Delete a plausible but wrong suggestion before adding
> more right ones.

## Checking what stuck

`list_blueprint_tags` on the [MCP server](/foliums/blueprintr-user-guide/developers/mcp-server)
returns each tag with its slug, label, provenance and taxonomy placement.

`set_blueprint_tags` replaces the whole set, so read before you write.

---

# Blueprintr User Guide: Templates and the Compendium
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/blueprints/templates-and-the-compendium

> Start from a prepared blueprint, and the three scopes a template can come from.


The **Compendium** is the template library. A template is a complete blueprint,
including its diagram, strata and prose, that you copy and edit.

## Three scopes

What you see in the Compendium comes from three places:

> [!FIELDS]
>
> > [!FIELD Personal|visible only to you|yours]
> >
> > Anything you captured for your own reuse.
>
> > [!FIELD Organisation or team|shared|your workspaces]
> >
> > Templates shared into an org or team you belong to. Everyone in the
> > workspace starts from the same structure.
>
> > [!FIELD Blueprintr defaults|shipped|everyone]
> >
> > Starting points that come with the product.

## Using one

Pick a template and create from it. You get a **private draft**: a blueprint
draft filed into your own portfolios, or for a diagram template, a private
vellum in your Drafts portfolio. The original is untouched either way.

Creating from a template never publishes anything, however public the template
was.

## Making one

Any blueprint you can edit can become a template from its admin menu, and so
can a standalone Vellum diagram, which gives a diagram-only starting point
rather than a whole blueprint.

Sharing it beyond yourself depends on the permissions your role gives you.

> [!NOTE]
> Through the [MCP server](/foliums/blueprintr-user-guide/developers/mcp-server),
> `create_template_from_blueprint` and `create_template_from_vellum` always
> produce a **personal** template. An agent can capture a template for you; it
> cannot publish one to your organisation.

## A template is a snapshot

Editing the source blueprint afterwards does not change the template, and
editing a copy does not change the source. `get_template` reports what a
snapshot contains before you commit to it.

---

# Blueprintr User Guide: Vellum
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum

> Blueprintr's own diagram editor, covering the canvas, the two layers and the drawing tools.

Vellum is Blueprintr's diagram editor and the default engine for any new
diagram. It runs inside the blueprint editor, as a standalone diagram, and as a
desktop app.

![blueprint:josh/drawing-in-vellum](https://blueprintr.io/embed/josh/drawing-in-vellum?exclude=cmtpw6i3w0003lduy20wilmv1&hideTabBar=1#h=640)

## Two layers

Every shape sits on one of two layers.

| Layer | For |
| --- | --- |
| **Blueprint** | The diagram itself. Shapes here can carry strata, be linked to, and be read by Continuum. |
| **Notes** | Working annotations. Stickies, questions, things to resolve. |

![The layer pills at the bottom left of the canvas: Notes, Both and Blueprint, with Both selected](/api/folium-assets/cmtozmo5h0001ykw4si3tkb4l/raw)

Press <kbd>W</kbd> to switch which layer you draw on. The pills at the bottom
left control which layers you can *see*, so you can hide the noise without
deleting it.

Press <kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>P</kbd> to promote a Notes item to
the Blueprint layer.

## Getting around

<kbd>Cmd</kbd> <kbd>K</kbd> searches every shape, icon and command.

<kbd>Cmd</kbd> <kbd>0</kbd> resets the view; <kbd>Cmd</kbd> <kbd>1</kbd> fits
everything to the viewport.

## Tools

![The Vellum toolbar: shape, connector, text, sticky, pen and icon tools, each labelled with its keyboard shortcut](/api/folium-assets/cmtozlgck00064yqzbj6v3zjs/raw)

| Key | Tool |
| --- | --- |
| <kbd>Q</kbd> | Tool lock, keeping a drawing tool active so you can drop several shapes in a row |
| <kbd>8</kbd> | Container, a frame you drag shapes into |
| <kbd>9</kbd> | Freehand pen, for annotating over the canvas |
| <kbd>L</kbd> | Laser pointer, a fading cursor trail for screen shares |

> [!TIP]
> The **Tips & shortcuts** button in the editor lists everything, always
> current. The [shortcuts page](/foliums/blueprintr-user-guide/vellum/keyboard-shortcuts)
> here mirrors it.

> [!TILES 3]
>
> === [Shapes and connectors](/foliums/blueprintr-user-guide/vellum/shapes-and-connectors)
>
> What you can draw, and how connectors attach.
>
> === [Icon packs](/foliums/blueprintr-user-guide/vellum/icon-packs-and-libraries)
>
> Thousands of vendor icons, plus your own.
>
> === [Other engines](/foliums/blueprintr-user-guide/vellum/draw-io-excalidraw-and-mermaid)
>
> draw.io, Excalidraw and Mermaid.

---

# Blueprintr User Guide: Shapes and connectors
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum/shapes-and-connectors

> The shape kinds, how containers nest, and how connectors attach and route.


## Shape kinds

| Kind | Notes |
| --- | --- |
| Rectangle, ellipse, diamond | The basics |
| Polygon | Any number of sides, plus star, cloud, callout and semicircle presets |
| Container | A frame that owns the shapes inside it. Moving it moves them |
| Group | A selection bound together without a visible frame |
| Icon | A glyph from an [icon pack](/foliums/blueprintr-user-guide/vellum/icon-packs-and-libraries) or your own SVG |
| Service | A labelled cloud- or platform-service block |
| Table | Rows and columns of cells |
| Text | A standalone label with no box |
| Note | A sticky, normally on the Notes layer |
| Image | A raster image |
| Freehand | Pen strokes |

## The inspector

Selecting a shape opens the inspector on the right: stroke and fill, fill
opacity, line weight, dash, prism, corner roundness and opacity under
**Appearance**; font, size and text colour under **Typography**; then the
shape's **Label** and **Body** text.

![The shape inspector: Appearance with stroke, fill, line, dash, prism, roundness and opacity, then Typography, Label and Body](/api/folium-assets/cmtp047zy00087bd7wthtspt2/raw)

## Containers

A container owns its children. Drag the container and everything inside moves;
resize it and the children stay put. Nesting is unlimited. Use one container
per boundary, whether that boundary is a VPC, a team, or a process stage.

Press <kbd>8</kbd> for the container tool, then drop shapes inside it.

## Connectors

Hover a shape and drag from its edge to draw a connector to another shape. The
endpoints stay attached when either shape moves.

| Gesture | Effect |
| --- | --- |
| <kbd>Alt</kbd> + drag | Pull an endpoint free of any shape, with no auto-snap |
| <kbd>Shift</kbd> + drag | Lock the connector to a horizontal or vertical line |
| Right-click a waypoint | Delete that bend |
| <kbd>Tab</kbd> | Reverse the connector's direction |

Routing is straight, curved or orthogonal per connector.

## Moving and resizing

| Gesture | Effect |
| --- | --- |
| <kbd>Cmd</kbd> + drag | Duplicate and drag the copy |
| <kbd>Alt</kbd> + drag | Move without snapping |
| <kbd>Shift</kbd> + drag | Lock to one axis |
| <kbd>Cmd</kbd> + resize | Resize from the centre |
| <kbd>Shift</kbd> + resize | Lock the aspect ratio |
| <kbd>Alt</kbd> + rotate | Rotate freely, skipping the 15° snap |

---

# Blueprintr User Guide: Styling and themes
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum/styling-and-themes

> Fills, strokes, fidelity, and keeping a diagram legible in both light and dark.

## Fills and strokes

Shapes take a fill and a stroke from a named palette rather than arbitrary hex.
Palette colours are theme-aware, so a diagram drawn in light mode stays legible
in dark mode.

> [!IMPORTANT]
> A hand-picked hex fill will not adapt. Use the palette on any diagram that
> will ever be read in dark mode. Anything on a public page will be.

## Make colour mean something

Use each hue for exactly one category, consistently. Give data stores one
colour, external systems another, and the subject of the diagram a third. A
rainbow of shapes where colour means nothing is harder to read than no colour
at all.

## Fidelity

Fidelity controls how hand-drawn the rendering looks, from a clean technical
line to a sketchier stroke. It is a per-shape property with a document default.

Sketchy reads as "draft, still moving". Clean reads as "this is the answer".
Keep one fidelity per diagram.

## Theme

<kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>D</kbd> toggles the editor between light
and dark. Check your diagram in both before publishing, to catch a fill that
only works in one.

---

# Blueprintr User Guide: Icon packs and libraries
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum/icon-packs-and-libraries

> Thousands of vendor icons, plus your own SVGs, available from the canvas search.

Vellum ships with vendor icon packs covering the major cloud providers and a
wide range of software and infrastructure vendors.

## Finding an icon

<kbd>Cmd</kbd> <kbd>K</kbd> searches icons alongside shapes and commands. Type
what the thing is, such as "lambda", "postgres" or "firewall", and insert the
match.

## Your own SVGs

Drag `.svg` files from your computer onto the canvas. They are added as icons
and saved to your personal library, so they are available in every diagram
afterwards.

## Libraries

**Dashboard → Libraries** controls which packs are enabled for your workspace
and holds the icons you have added yourself. Organisations can curate the list
so a team's diagrams stay visually consistent.

> [!IMPORTANT]
> Icons already saved in a diagram are never rewritten. If a pack is later
> disabled or its licensing changes, existing diagrams keep the artwork they
> were drawn with. Only what you can newly insert changes.

## Licensing

Vendor marks are supplied under the terms their owners publish, and those terms
vary. Check [licences](https://blueprintr.io/licenses) before using a vendor
mark in material you distribute outside Blueprintr.

---

# Blueprintr User Guide: draw.io, Excalidraw and Mermaid
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum/draw-io-excalidraw-and-mermaid

> Three alternative diagram engines, when to use each, and what you give up.


Vellum is the default engine. Three others are available from the engine menu
on any diagram tab, and a blueprint can mix them.

> [!ACCORDIONS]
>
> === draw.io
>
> The full draw.io editor, self-hosted. Choose it when you have existing
> `.drawio` files, or when you need a stencil that only draw.io has.
>
> === Excalidraw
>
> Hand-drawn style, fast for rough thinking. Choose it for sketches that are
> meant to look provisional.
>
> === Mermaid
>
> Diagrams as text. Choose it for sequence diagrams, state charts and
> gantt charts, and for anything you would rather edit and diff as text.

## What you give up

Strata bind to shapes on any engine, so layered detail works everywhere. The
difference is elsewhere:

| | Vellum | draw.io | Excalidraw | Mermaid |
| --- | --- | --- | --- | --- |
| Strata on shapes | Yes | Yes | Yes | Yes |
| Live collaboration | Yes | No | No | No |
| Continuum can write to it | Yes | No | No | No |
| Icon packs | Yes | Own stencils | Limited | No |
| Podium presentation | Yes | No | No | No |

## Changing your default

**Settings → General** sets which engine new diagrams start in.

> [!NOTE]
> Switching engines on an existing tab does not convert the drawing. Pick the
> engine when you create the tab.

---

# Blueprintr User Guide: Live collaboration
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum/live-collaboration

> Several people on one Vellum canvas, the four roles, and how guests are admitted.

Vellum diagrams saved to the cloud can be edited by several people at once.
Cursors, selections and edits appear live.

## Roles

Access is per-diagram, and the role decides what someone can do.

| Role | Can |
| --- | --- |
| **Owner** | Everything, plus admin: toggle collaboration, mint invites, admit or deny guests |
| **Write** | Full editing, no admin |
| **Read** | Laser pointer, and their own sticky notes on the Notes layer |
| **View** | Presence only. Their cursor is visible and they change nothing |

A reviewer with the Read role can point at things and leave notes without any
risk of moving your shapes. Notes left by others are badged with the author's
name and colour.

## Inviting

Open the collaboration panel from the editor. Each diagram has two invite
links, one granting write and one granting read. Share the one you mean.

## Guests

Someone who is not signed in and follows an invite lands in a **lobby** rather
than the canvas. The owner sees them queued and clicks Allow or Deny. Signed-in
users skip the lobby.

## Where it works

Live collaboration is a Vellum feature. draw.io, Excalidraw and Mermaid tabs
are single-editor.

---

# Blueprintr User Guide: Desktop app
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum/desktop-app

> Two desktop builds, the signed-in app and Vellum Core, which edits local files with no account.

[blueprintr.io/download](https://blueprintr.io/download) offers two different
builds.

> [!TILES 2]
>
> === Blueprintr Vellum
>
> The full editor in a native window, signed in to your account. Diagrams are
> the same cloud saves as on the web. **Recommended.**
>
> === Vellum Core
>
> The canvas on its own, saving to local files, with no account and no network
> connection.

macOS, Windows and Linux.

## Blueprintr Vellum

The same editor as the web version, without browser chrome, with its own dock
icon and smoother rendering on high-refresh displays.

Sign-in is handed to your normal browser rather than asked for in the window,
so you authenticate where your password manager already works and the browser
hands the session back.

There is no separate desktop file type and no separate account. Open the same
diagram in the browser and you see the same content, including anything a
collaborator changed while you were in the app.

The app updates itself and prompts you when a new version is ready.

## Vellum Core

Core is the drawing canvas without the rest of Blueprintr. Diagrams are files
on your machine.

> [!IMPORTANT]
> Core edits a file. Strata, publishing, collaboration and cloud history are
> Blueprintr features and are absent from Core. Work done in Core reaches
> Blueprintr only when you import it.

## Which to install

Install Blueprintr Vellum if you have an account. Install Core when the work
cannot leave the machine, or when you want a diagram tool with no service
behind it.

---

# Blueprintr User Guide: Keyboard shortcuts
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/vellum/keyboard-shortcuts

> The full Vellum shortcut list, mirroring the editor's own Tips & shortcuts panel.


On macOS the modifier is <kbd>Cmd</kbd>; elsewhere it is <kbd>Ctrl</kbd>. The
editor's **Tips & shortcuts** button shows the same list with the right keys
for your platform.

## Find and select

| Keys | Does |
| --- | --- |
| <kbd>Cmd</kbd> <kbd>K</kbd> | Search every shape, icon and command |
| <kbd>Cmd</kbd> <kbd>F</kbd> | Find and replace across labels, body text, table cells and connector labels |
| <kbd>Cmd</kbd> <kbd>A</kbd> | Select everything visible |
| <kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>A</kbd> | Deselect all |
| <kbd>Shift</kbd> + click | Add or remove one shape from the selection |
| <kbd>F2</kbd> | Edit the selected shape's label |

## Transform

| Keys | Does |
| --- | --- |
| <kbd>Cmd</kbd> <kbd>G</kbd> / <kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>G</kbd> | Group / ungroup |
| <kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>[</kbd> / <kbd>]</kbd> | Send to back / bring to front. Plain <kbd>[</kbd> and <kbd>]</kbd> step one layer |
| <kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>.</kbd> / <kbd>,</kbd> | Font size up / down by 1px |
| <kbd>Shift</kbd> + <kbd>H</kbd> / <kbd>V</kbd> | Flip horizontally / vertically |

## Layers

| Keys | Does |
| --- | --- |
| <kbd>W</kbd> | Switch the layer you draw on, Blueprint or Notes |
| <kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>P</kbd> | Promote selected Notes items to the Blueprint layer |

## View

| Keys | Does |
| --- | --- |
| <kbd>Cmd</kbd> <kbd>0</kbd> / <kbd>1</kbd> | Reset the view / fit everything to the viewport |
| <kbd>Cmd</kbd> <kbd>;</kbd> | Toggle the major-gridline overlay |
| <kbd>Shift</kbd> <kbd>Cmd</kbd> <kbd>D</kbd> | Toggle light and dark theme |
| <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | Previous / next diagram tab |

## Tools

| Keys | Does |
| --- | --- |
| <kbd>Q</kbd> | Tool lock |
| <kbd>8</kbd> | Container tool |
| <kbd>9</kbd> | Freehand pen |
| <kbd>L</kbd> | Laser pointer |

> [!TIP]
> Drop `.svg` files from your computer straight onto the canvas. They become
> icons, and are added to your personal library.

---

# Blueprintr User Guide: Strata
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/strata

> Detail bound to one shape on a diagram, opened by clicking that shape.

A stratum is a block of detail attached to one shape. The reader clicks the
shape and the detail opens beside it, with the diagram still on screen.

![blueprint:josh/anatomy-of-a-stratum](https://blueprintr.io/embed/josh/anatomy-of-a-stratum#h=520)

In a long page of prose the reader has to work out which paragraph belongs to
which box. A stratum removes the guess: the detail has exactly one owner, and
the owner is the thing they are already looking at.

## What a stratum holds

A stratum is a set of tabs, and each tab has a kind. One stratum can mix them:
an overview in Rich, the config it describes in Raw, and a Subdiagram that
opens the box up.

| Kind | Holds |
| --- | --- |
| Rich | Markdown, images, embedded diagrams |
| Raw | Code or config, rendered line-numbered |
| Subdiagram | A diagram of its own, in any supported engine |
| Image | A single image, uploaded or linked |
| Embed | An embeddable URL. YouTube and Google Maps links convert automatically |

## Adding one

Right-click the shape and choose **Add Stratum…**. The modal opens already
bound to that shape.

Right-click the same shape later and the item reads **Edit Stratum…**. Shapes
carrying a stratum are marked on the canvas.

> [!TIP]
> A stratum does not have to be created from the shape. The link picker binds
> an existing stratum to any shape on any surface in the blueprint, including
> diagrams embedded inside rich text. See [Linking strata](/foliums/blueprintr-user-guide/strata/linking-strata).

## What readers get

Hovering a marked shape for half a second shows a preview card with the
stratum's name and its opening lines. Clicking opens it in a window that moves
and resizes by its corners, or docks to a panel down the right-hand side at
half the viewport width.

Readers can leave the panel open and work through several strata in turn while
the diagram stays put.

> [!TILES 3]
>
> === [Creating and editing](/foliums/blueprintr-user-guide/strata/creating-and-editing)
>
> The modal, the tabs, and what happens on save.
>
> === [Tab kinds](/foliums/blueprintr-user-guide/strata/tab-kinds)
>
> What each kind renders, and when to use it.
>
> === [Linking strata](/foliums/blueprintr-user-guide/strata/linking-strata)
>
> The picker, the `stratum:` link scheme, and multi-target links.

---

# Blueprintr User Guide: Creating and editing
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/strata/creating-and-editing

> Three ways to create a stratum, and what the editor holds once one exists.

![blueprint:josh/creating-a-stratum](https://blueprintr.io/embed/josh/creating-a-stratum?exclude=cmtpwd5jo001j11r44fw410t7&hideTabBar=1#h=620)

## From the shape

Right-click a shape on any diagram in the blueprint and choose
**Add Stratum…**. The stratum is created and anchored to that shape as soon as
you choose it, so the modal opens on a stratum that already exists. Close it
without typing and the stratum stays; fill in the content later if you would
rather keep drawing.

This is the normal path. It is available in step 1 of the editor as well as
step 2, so you can write detail while the diagram is still taking shape.

Once a shape carries a stratum, the same menu reads **Edit Stratum…** and the
shape is marked on the canvas.

## From the Resources & Strata step

Step 2 lists every stratum in the blueprint. **Add Stratum** here creates one
that is not yet bound to anything; use the [link picker](/foliums/blueprintr-user-guide/strata/linking-strata)
to point it at a shape afterwards.

Use it when you are writing several strata in one sitting and binding them
later, or when the detail exists before the drawing does.

## From a diagram embedded in prose

A diagram inside a Rich Text tab has its own kebab menu with **Add Stratum…**.
Strata bound to an embedded diagram behave exactly like those on a tab canvas.

## Inside the editor

A stratum has a **name**, and one or more **tabs**. The name is what readers
see on the hover preview and in the window's title bar, so write it as a label
rather than a sentence.

> [!TIP]
> Give the stratum the same name as the shape unless there is a reason not to.
> A reader who clicks "Order queue" expects a window titled "Order queue".

![The stratum modal: icon, name and kind on one row, the anchor below it with Change, Remove and + Add, then the tab strip](/api/folium-assets/cmtp06kci0001tjm2smu5oluz/raw)

Add a tab with **Add tab** and choose its
[kind](/foliums/blueprintr-user-guide/strata/tab-kinds). Reorder tabs by
dragging; the first is what opens by default.

The **Anchor** row shows what the stratum is attached to. **Change** repoints
it, **Remove** detaches it, and **+ Add** anchors the same stratum to another
shape, for detail that belongs to two places on a drawing.

## Deleting

Deleting a stratum that something links to leaves those links dangling, and
the reader sees them as missing. The delete confirmation lists the referrers
first: inline `stratum:` links, linked callouts, and any stratum whose
diagram link points inside the one you are removing. Read that list before
confirming.

---

# Blueprintr User Guide: Tab kinds
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/strata/tab-kinds

> What Rich, Raw, Subdiagram, Image and Embed each render, and when to use them.

Every tab in a stratum has a kind, chosen when you add it. One stratum can mix
them freely.

> [!ACCORDIONS]
>
> === Rich
>
> Markdown, with images and embedded diagrams. The default. Use it for
> explanation.
>
> It is the same editor used for a blueprint's Rich Text tabs and for folium
> pages, so the whole [component library](/foliums/blueprintr-user-guide/blueprints/content-blocks)
> is available: callouts, steps, tables, accordions.
>
> === Raw
>
> Plain text rendered as a line-numbered block with syntax highlighting.
>
> Use it for the thing itself: a config file, a command, a schema, a log
> excerpt. Prose that happens to be short belongs in Rich.
>
> === Subdiagram
>
> A diagram of its own, drawn in Vellum, draw.io, Excalidraw or Mermaid.
>
> A box labelled "Payments" on a context diagram can hold the payments
> service's own component diagram, and that diagram's shapes can carry their
> own strata.
>
> === Image
>
> A single image, uploaded or referenced by URL.
>
> === Embed
>
> An embeddable URL. YouTube and Google Maps links are converted to their
> embed form automatically. Other URLs are accepted with a warning, because
> not every site permits framing.

## Choosing

| You have | Use |
| --- | --- |
| An explanation | Rich |
| A file, command or schema | Raw |
| Another diagram's worth of detail | Subdiagram |
| A photo, screenshot or rendered chart | Image |
| A video, map or dashboard | Embed |

> [!NOTE]
> A Subdiagram tab's shapes can carry strata of their own. There is no depth
> limit, but past three levels the thing you are drawing is usually better as
> its own blueprint.

---

# Blueprintr User Guide: Linking strata
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/strata/linking-strata

> The link picker, the stratum link scheme, multi-target links and tab fragments.


A stratum is always *bound* to a shape on a surface. It can also be *linked to*
from prose.

![blueprint:josh/stratum-binding-vs-linking](https://blueprintr.io/embed/josh/stratum-binding-vs-linking#h=520)

## Binding with the picker

The link picker opens the diagram in a read-only pick view. Click the shape you
mean and the stratum binds to it.

The surface can be a diagram tab's own canvas, or a diagram embedded inside
rich or raw content elsewhere in the blueprint. The binding is what lets a
reader's click resolve to the right stratum when a blueprint holds several
diagrams.

## Linking from prose

Markdown links accept a `stratum:` scheme:

```markdown
[see the auth flow](stratum:clx1a2b3c4)
```

Following the link opens that stratum, the same as clicking its shape.

> [!FIELDS]
>
> > [!FIELD One id|scheme|required]
> >
> > `stratum:` followed by a single stratum id.
>
> > [!FIELD Several ids|list|optional]
> >
> > Comma-separated. All open together.
>
> > [!FIELD With a tab|fragment|optional]
> >
> > Add `#tab=2` to open on a particular tab rather than the first.

Callouts take the same target, so a whole note becomes the link:

```markdown
> [!NOTE|stratum:clx1a2b3c4] Where this is enforced
```

> [!IMPORTANT]
> The `stratum:` scheme is understood by Blueprintr's editors and reader only.
> Everywhere else it is inert. Exported markdown never contains a broken
> external link, but the link will not resolve either. Export with that in
> mind.

## Legacy links

Content written before strata were renamed used a `stage:` prefix. Blueprintr
still reads `stage:` links and writes new ones as `stratum:`, so old blueprints
keep working with no migration.

---

# Blueprintr User Guide: What readers see
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/strata/what-readers-see

> Hover previews, the floating window, and the dock a stratum opens into.


Strata stay out of the way until a reader wants them.

![blueprint:josh/reading-a-blueprint](https://blueprintr.io/embed/josh/reading-a-blueprint?exclude=cmtpw7gm9000tlduy9serbxzs&hideTabBar=1#h=640)

## Marked shapes

A shape carrying a stratum is marked on the canvas. The mark is the only change
to the drawing, and a reader who never clicks one still sees the complete
diagram.

## Hover

Hovering a marked shape for half a second shows a preview card with the
stratum's name and its opening lines. Enough to decide whether to click.

## The window

Clicking opens the stratum in a floating window. Readers can move it, resize it
from any corner, maximise it, or minimise it to a strip.

## The dock

The window can be docked to a panel down the right-hand side, half the viewport
wide by default and draggable from there. The page reflows around it rather
than being covered.

Dock the panel to work through a diagram shape by shape while the drawing stays
put.

> [!TIP]
> The dock only appears on a blueprint's own page. In an
> [embed](/foliums/blueprintr-user-guide/sharing/embedding-blueprints) there is no page to
> reflow, so strata open as floating windows inside the embed's frame.

---

# Blueprintr User Guide: Foliums
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums

> A multi-page documentation site with a nav tree, an automatic contents list, search and its own domain. This guide is one.


A folium is a documentation site. Left rail of pages, content in the middle,
automatic table of contents on the right. Use one when the thing you are
writing runs longer than a single blueprint: a handbook, a reference, a set of
runbooks.

You are reading one now.

![blueprint:josh/setting-up-a-documentation-site](https://blueprintr.io/embed/josh/setting-up-a-documentation-site?exclude=cmtpvgbim000a8sqftldqrm2o&hideTabBar=1#h=620)

## Folium or blueprint?

| | Blueprint | Folium |
| --- | --- | --- |
| Shape | One subject, a few tabs | Many pages, a nav tree |
| Centre of gravity | A diagram | Prose, with diagrams in it |
| Navigation | Tab strip | Nav tree and contents list |
| Own domain | No | Yes |
| Reader search | Site-wide | Scoped to the folium |

A folium page can embed a blueprint, which keeps the diagram a first-class
object instead of a screenshot.

## Ownership

Foliums are owned by an organisation and require a
[Teams licence](/foliums/blueprintr-user-guide/teams/setting-up-an-organisation). They are
served from the organisation's subdomain, or a custom domain if one is
configured.

> [!TILES 3]
>
> === [Pages and navigation](/foliums/blueprintr-user-guide/foliums/pages-and-navigation)
>
> The tree, page kinds, ordering and icons.
>
> === [Writing](/foliums/blueprintr-user-guide/foliums/writing-pages)
>
> Frontmatter, components, includes and variables.
>
> === [Settings](/foliums/blueprintr-user-guide/foliums/settings-reference)
>
> Every configuration key in one place.
>
> === [The CLI](/foliums/blueprintr-user-guide/foliums/docs-cli)
>
> Write in your own editor, validate offline, push.
>
> === [API reference](/foliums/blueprintr-user-guide/foliums/api-reference-and-playground)
>
> Render an OpenAPI spec with a live playground.
>
> === [Reader authentication](/foliums/blueprintr-user-guide/foliums/reader-authentication)
>
> Docs behind a login.

---

# Blueprintr User Guide: Pages and navigation
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/pages-and-navigation

> The page tree, the four page kinds, ordering, icons, drafts and redirects.


A folium is a tree of pages. Depth and page count are capped generously; the
practical limit is what a reader can navigate.

## Page kinds

| Kind | Behaves as |
| --- | --- |
| **Doc** | An ordinary content page |
| **Section** | A heading in the nav with no content of its own |
| **Link** | A nav row pointing at another page |
| **External** | A nav row pointing off-site |

> [!TIP]
> Prefer a Doc with a short intro and a tile grid over a bare Section. A
> section header that cannot be clicked is a dead end for anyone who lands on
> it from search.

## Ordering and icons

Drag rows in the manage view to reorder. Each page takes an optional icon from
a curated Lucide set; a page without one gets a disc.

A page can be hidden from the nav and stay reachable by URL. Use that for a
page that is only ever linked from elsewhere.

## Slugs and redirects

A page's slug is its URL segment, and the full path is built from its
ancestors. Changing a slug or moving a page **records a redirect
automatically**, so old links keep working with a 308.

> [!IMPORTANT]
> Renaming is cheap because of that redirect. Deleting a page also deletes its
> inbound redirects, so old links to it 404.

## Drafts

A page can be published or draft. Draft pages are invisible to readers and are
excluded from search and from embeds. The `link-draft` diagnostic flags any
published page that links to one.

## Sizing the tree

Ten collapsed top-level groups is comfortable. Beyond that, readers stop
scanning the rail and rely on search instead.

---

# Blueprintr User Guide: Writing pages
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/writing-pages

> Frontmatter keys, the component library, includes, variables and audience splitting.


Folium pages are markdown, edited either in the browser or
[in your own editor](/foliums/blueprintr-user-guide/foliums/docs-cli).

## Frontmatter

| Key | Does |
| --- | --- |
| `title` | The page title. Falls back to the first heading, then the filename |
| `slug` | The URL segment |
| `description` | Rail subtitle, search snippet and meta description |
| `icon` | A curated Lucide name |
| `status` | `published` or `draft` |
| `hideInNav` | Keep it reachable but out of the rail |
| `kind` | `doc`, `section`, `link` or `external` |

> [!IMPORTANT]
> Do not start the body with an `# H1`. The reader chrome already renders the
> title, so a leading heading prints it twice.

## Components

The [component library](/foliums/blueprintr-user-guide/blueprints/content-blocks)
is available in full: callouts, steps, tabs, accordions, tiles, fields, trees
and the rest. It is the same pipeline that renders blueprint rich text.

## Includes

A fragment can be written once and included in several pages, so a warning or
a set of prerequisites has one source. Editing the fragment updates every page
that includes it.

## Variables

Settings can define variables that pages interpolate: a product version, a
base URL, a support address. Changing the value updates every page at once.

## Audience splitting

`[!VISIBILITY agents]` content is stripped before the page reaches a human, and
`[!VISIBILITY humans]` content is stripped from the markdown an agent fetches.
Use it for machine-readable hints that would clutter the page.

> [!NOTE]
> The split happens at the source layer, so bytes marked `agents` never reach
> a human reader's HTML.

---

# Blueprintr User Guide: Settings reference
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/settings-reference

> Every folium configuration key, grouped by layout, chrome, content behaviour and features, plus version snapshots.

A folium's configuration is in one place, reachable from **Manage →
Settings**. Everything below is optional and fails closed: a feature is off
until you turn it on.

## Where each control is

Two surfaces sit above the settings keys. **Customize** is the panel that
opens beside the page you are reading. **Manage** is a full page.

| Customize tab | Sets |
| --- | --- |
| **Theme** | Preset palettes, primary and accent colour, colour mode, logos |
| **Layout** | The left rail, the contents list, previous and next links |
| **Share** | Title and description |
| **Sources** | External source connections, shown only when the folium has them |
| **Redirects** | Old paths that should forward to new ones |
| **Versions** | Published snapshots readers can switch between |
| **Languages** | Locales the folium is published in |

| Manage section | Sets |
| --- | --- |
| **Visibility** | Who can read it, the shared password, the share link |
| **People** | Collaborators and their roles |
| **Change requests** | Edits waiting for review |
| **Settings** | Every key documented below |
| **MCP** | The agent endpoint, served for public password-free foliums |
| **Reader identity** | Sign-in through your own identity provider |
| **Export**, **Changelog**, **API spec**, **Repo sync** | The features of the same name |

## Layout

| Key | Controls |
| --- | --- |
| `showNav`, `navWidth` | The left rail and its width |
| `showToc`, `tocWidth`, `tocDepth` | The contents list and how many heading levels it shows |
| `collapsibleNav`, `sectionsCollapsedByDefault` | Whether groups collapse, and their initial state |
| `showPrevNext` | Previous and next links at the foot of each page |
| `relatedTopics` | A related-topics block under the content |

## Chrome

| Key | Controls |
| --- | --- |
| `navbar` | Top-nav links and the primary call to action |
| `footer` | Footer link columns and social links |
| `banner` | A site-wide banner above the reader chrome |
| `errors` | Custom 404 and error surfaces |

## Content behaviour

| Key | Controls |
| --- | --- |
| `variables` | String substitutions available to every page |
| `markdown` | How `.md` exports are composed for agents |
| `contextual` | The per-page "copy" and "open in an AI tool" menu |
| `requirePublishApproval` | Whether publishing a page needs a second person |

## Features

| Key | Controls |
| --- | --- |
| `search` | Reader search ranking, filters and prompt |
| `assistant` | The docs assistant and its embeddable widget |
| `api` | API-reference rendering and the request playground |
| `changelog` | The changelog feed and email subscriptions |
| `analytics` | Your own third-party measurement ids |
| `seo` | Indexing posture and extra meta tags |

> [!IMPORTANT]
> Settings are sent to the reader's browser. Never put a secret in them.
> Credentials for reader authentication and repo sync are stored separately,
> encrypted, and are never part of this object.

## Versions and rollback

A version is a manual snapshot of the site, taken from the **Versions** tab of
the **Customize** panel. Type a label, press **Publish version**, and readers
gain a selector in the top bar. **Latest** there is the live working set you
edit.

The snapshot captures your published, non-archived pages and their strata.
Nothing else. Every key on this page, along with the theme, custom domain,
redirects and uploaded assets, is served live, so editing any of them changes
what a pinned version looks like today. A version is also served in the
folium's default language whatever the reader picks, and editing is switched
off while a version is selected.

> [!IMPORTANT]
> There is no restore. Nothing copies a snapshot back over your live pages, so
> a version cannot undo an edit. The only control a version gives you is **Set
> default**, which decides where a reader lands when no version is named in the
> URL. Blueprint version history is a different mechanism: a blueprint has
> **Restore this version**, which rolls its live content back.

The first version you publish becomes the default at once, so readers move off
Latest the moment it exists. **Clear default (readers see Latest)** puts them
back.

Deleting a version takes effect on the click, with no confirmation and no undo.
The snapshot goes; the pages it was taken from stay.

A folium with no published page refuses with *Nothing to publish yet*, and one
whose pages and strata serialise past roughly 4 MB refuses with *This folium is
too large to snapshot*. Where `requirePublishApproval` is on and you are not a
folium admin, **Publish version** files a change request for an admin to review
rather than writing the snapshot.

## Analytics and consent

Third-party measurement ids you configure here are consent-gated, and are never
mounted on an embed surface. An embed writes nothing to the reader's device.

---

# Blueprintr User Guide: Branding and theming
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/branding-and-theming

> Colours, logo, navbar, footer and banner, and how a folium inherits its look from the organisation.

A folium takes its look from the owning organisation, then lets you override
the theme, navbar, footer and banner.

## Theme

Pick a preset or set colours directly. The reader's light or dark preference is
respected either way, so choose colours that work in both.

## Navbar

Link columns across the top, plus one primary call to action. Keep it to one; a
navbar with four equally weighted buttons has no call to action.

## Footer

Link columns and social links. Social keys come from a fixed list rather than
an open map, so the footer can only render icons it has.

## Banner

A site-wide strip above the reader chrome, in one of four tones. Use it for
something time-bound, such as a migration window or a deprecation date, and
take it down when that window closes.

## Custom domain

An organisation can serve its folia from
[its own domain](/foliums/blueprintr-user-guide/sharing/subdomains-and-custom-domains).

---

# Blueprintr User Guide: Reader search
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/reader-search

> What search covers, the ranking and filter settings, and why an editor's results include drafts.

Every folium has its own search, scoped to that folium. It covers page titles
**and** page bodies, so a reader can find a paragraph rather than only a page
name, and the result shows the matching excerpt.

## What each reader sees

Search mirrors exactly what the person searching can open:

| | Sees |
| --- | --- |
| Anyone who can edit | Published pages **and drafts** |
| Everyone else | Published pages only |

It also follows the reader's context: the pinned version when one is selected,
and the translations for the locale they are viewing.

> [!IMPORTANT]
> A page you can find, a reader may not. Before concluding search is broken,
> check whether the page is still a draft.

## Settings

**Manage → Documentation settings → Search.**

> [!FIELDS]
>
> > [!FIELD prompt|placeholder|optional]
> >
> > The placeholder in the rail's search box. Leave it empty for the built-in.
>
> > [!FIELD boostTitles|0–10|ranking]
> >
> > How much more a title match counts than a body match.
>
> > [!FIELD boostHeadings|0–10|ranking]
> >
> > The same for a heading match.
>
> > [!FIELD filters|locales, sections|optional]
> >
> > Whether readers get filter controls for locale and section.
>
> > [!FIELD maxResults|1–24|default]
> >
> > Hits returned. **24 is the server's scan cap**, so asking for more does not
> > widen the search. Tune the boosts instead.

## Page descriptions

Write a `description` on every page. The result snippet falls back to it, and
link previews show it.
[Diagnostics](/foliums/blueprintr-user-guide/foliums/diagnostics) has a
`missing-description` rule.

## Search analytics

[Analytics](/foliums/blueprintr-user-guide/foliums/folium-analytics) records what readers
searched for, which terms returned nothing, and which results were clicked. A
term with searches and a 0% click-through is a ranking or naming problem: the
page exists, and its title does not read as the answer.

## Hidden pages are still readable

> [!IMPORTANT]
> Hiding a page from the nav only removes it from the rail. A hidden published
> page is still findable and still readable at its URL. If a page must not be
> read, make the folium private or put it behind
> [reader authentication](/foliums/blueprintr-user-guide/foliums/reader-authentication).

---

# Blueprintr User Guide: Docs assistant
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/docs-assistant

> A question box over your documentation, and the widget that embeds it elsewhere.

The assistant answers questions using the folium's own pages as its source. It
is off until you enable it.

## What it can see

Only the folium's published content, plus the prompt material you supply in
settings. It has no access to anything outside the folium.

## Prompt material

Settings hold instructions for the assistant: tone, what to do when it does
not know, which pages to prefer. Write them as guidance to a person rather
than as configuration.

> [!TIP]
> Cover what the assistant should do when the docs do not answer the question.
> "Say you do not know and link the support page" keeps it from inventing an
> answer.

## The widget

The assistant can be embedded on another site as a widget, so your product's
own UI can answer documentation questions in place.

## What it will not do

The assistant does not edit pages. Asked for a change, it files a
[change request](/foliums/blueprintr-user-guide/blueprints/discussion-and-change-requests) for a
person to review.

---

# Blueprintr User Guide: API reference and playground
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/api-reference-and-playground

> Generate reference pages from an OpenAPI or AsyncAPI document, and what re-importing does to them.

Import an OpenAPI or AsyncAPI document and the folium generates reference
pages in the same chrome as the rest of your documentation: endpoints,
parameters, request and response shapes.

**Manage → API specs.**

## Importing

Each import is filed under a **key** you choose. The key controls what happens
when you import again:

> [!IMPORTANT]
> Re-importing the **same key** replaces the previously generated subtree. The
> old pages are archived, not deleted. Import under a *new* key and you get a
> second reference section rather than an updated one.

A versioned API is two keys. A moving API is one key re-imported.

Give it a source URL or paste the document. A pasted body takes precedence
over the URL.

> [!NOTE]
> A source URL is fetched **server-side, through the shared request guard**.
> Private, link-local and metadata addresses are refused. A spec URL that only
> resolves inside your network will not import.

## The playground

Each endpoint can have a live request panel: fill in parameters, send, and see
the response. Requests are proxied, so the reader's browser does not make
cross-origin calls to your API directly.

> [!IMPORTANT]
> The playground needs a signing secret configured on the platform side. Until
> that is in place it degrades to read-only: the panel renders and **Send** is
> disabled. The secret is configured during deployment and cannot be switched
> on from folium settings.

## In exports

The [reader menu](/foliums/blueprintr-user-guide/foliums/settings-reference) has an
**Inline the resolved API schema in `.md` exports** option. With it on, an
agent that pulls the markdown gets the schema inline rather than a link to it.

## Writing by hand

You do not have to import anything. The
[`[!FIELDS]` component](/foliums/blueprintr-user-guide/blueprints/content-blocks) produces
the same parameter and response layout from markdown, for a small API or for a
single endpoint described in prose rather than generated from a schema that
documents forty.

---

# Blueprintr User Guide: Changelog and subscribers
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/changelog-and-subscribers

> A dated feed of what changed, an RSS feed, and email subscriptions.

A folium can publish a changelog: dated entries, each anchored so it can be
linked to directly.

## Writing an entry

```markdown
> [!UPDATE v2.1.0|2026-09-05]
>
> The playground now remembers the last request per endpoint.
```

Entries are ordinary page content and can hold anything a page can, including
diagrams.

## Feeds

The changelog is published as a feed at `changelog.xml`, alongside the folium's
`rss.xml`. Readers can subscribe in a feed reader without an account.

## Email subscriptions

Readers can also subscribe by email and be notified when you publish a new
entry. Off by default.

> [!NOTE]
> Subscriptions collect an email address from your readers. Say so where you
> ask for it, and make sure your privacy notice covers it.

---

# Blueprintr User Guide: Reader authentication
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/reader-authentication

> Setting who can read a folium, from private through unlisted with a password to public, and layering reader identity on top.

Reader access is set on the folium's **Manage** page, in the **Visibility**
section at the top. Only a folium admin or owner can change it.

## The three levels

| Level | Who can read it |
| --- | --- |
| **Private** | Signed-in members of the owning organisation |
| **Unlisted** | Anyone with the link, optionally behind a shared password |
| **Public** | Anyone, including search engines |

Private is the default for a new folium, and the Teams licence gate applies.

## Changing it

Open the folium, choose **Manage**, then pick a level under **Visibility**.
The change saves on click; there is no separate save step.

> [!NOTE]
> An editor-tier collaborator cannot change this. Visibility and the shared
> password are reserved for admins and owners, so the buttons are disabled
> for anyone else.

## Unlisted with a password

An unlisted folium can carry a shared password. Readers enter it once and a
cookie remembers them. That covers a client handover, but records no reader
identity, so it cannot tell you who read what.

> [!IMPORTANT]
> Revoking one person's access to a shared password means changing it for
> everyone.

## What public changes

Private and unlisted foliums are served `noindex, nofollow`. Public is the
only level a search engine will index.

A public folium with no password is also served an MCP endpoint, listed under
**MCP** on the Manage page, so agents can search and read it. Setting a
password or moving back to unlisted withdraws that endpoint.

## Reader identity

Readers authenticate against your identity provider and get a session tied to
who they are. That session supports per-reader access and per-reader records
of who read what. It layers on top of the level above rather than replacing
it.

> [!NOTE]
> Reader identity depends on an authentication route being reachable on the
> host your folium is served from. On a subdomain or custom domain that
> requires the edge configuration to be in place; without it readers stay
> anonymous. Check with whoever operates your deployment before relying on it.

---

# Blueprintr User Guide: Repo sync
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/repo-sync

> Keep a folium and a GitHub or GitLab repository in step. Cloud only, and pushes land on a new branch.


A folium can be connected to a markdown repository so the same content exists
in both places. GitHub and GitLab, cloud only.

> [!IMPORTANT]
> Self-hosted GitHub Enterprise and self-managed GitLab are **not supported**.

## Configuring it

> [!FIELDS]
>
> > [!FIELD Provider|GitHub or GitLab|required]
> >
> > Cloud only.
>
> > [!FIELD Repository and branch|the target|required]
> >
> > Plus an optional **base path**, so documentation can sit in a
> > subdirectory of a larger repository.
>
> > [!FIELD Direction|one of three|required]
> >
> > Repository → Folium, Folium → repository, or both.
>
> > [!FIELD Access token|encrypted at rest|required]
> >
> > A pull needs read access. A push needs write: on GitHub, **Contents: read
> > and write**; on GitLab, **Developer** with the `api` scope.

The token is encrypted before storage and is never shown again, sent to the
browser, or written to a log. It is not part of the settings object, so it
cannot reach a reader.

> [!NOTE]
> If your deployment has not provisioned `FOLIUM_REPO_SYNC_KEY`, connecting is
> **refused** rather than storing the token in the clear. Ask whoever operates
> your deployment to provision it.

## Pull

Markdown files in the repository become pages. Documentation sits beside the
code, is reviewed the same way, and the folium is the published surface.

## Push

Pages are written back as **a new branch** for you to review in your
repository. Push never commits directly to your default branch.

> [!IMPORTANT]
> A pushed branch has no preview URL of its own. A folium builds one live site
> per document, not one per branch, so review a pushed branch in your
> repository. If your workflow depends on a preview deployment per branch,
> repo sync will not give you that.

## The alternative

To author locally without connecting a repository, the
[CLI](/foliums/blueprintr-user-guide/foliums/docs-cli) pulls and pushes a directory of
markdown over the API. It uses no Git and stores no token on our side. It also
validates against the server's own rules offline before it uploads anything,
which repo sync does not.

---

# Blueprintr User Guide: Automations
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/automations

> The documentation agent, pointed at your folium, filing change requests you review like any other proposal.


An automation runs the documentation agent over the folium and files a
**change request** with what it proposes.

> [!IMPORTANT]
> Nothing is applied automatically. Every proposal lands in
> [change requests](/foliums/blueprintr-user-guide/foliums/pages-and-navigation) and is
> reviewed exactly like a human suggestion. An automation cannot publish, and it
> cannot edit a page directly.

The agent is allowed to be wrong, because a wrong proposal costs a rejection
rather than a corrupted page.

## Predefined automations

Start from one of these rather than describing a job from scratch:

> [!TILES 2]
>
> === Fix broken links
>
> Finds internal links that resolve to nothing and proposes the target it
> thinks you meant.
>
> === Refresh stale pages
>
> Looks for pages that have drifted from what the rest of the folium says.
>
> === Improve page descriptions
>
> Writes a `description` where one is missing or generic. That string becomes
> the search snippet and the link preview.
>
> === Normalise terminology
>
> Finds the same concept called three different things and proposes one.

**New automation** takes your own instruction instead.

## Reviewing a run

A run produces a change request. Open it, read what it proposes, and accept,
edit or reject page by page. A rejected proposal leaves the page untouched.

## When to use diagnostics instead

Diagnostics is a rule engine, not a model. It is exact, costs nothing, and
finishes in seconds. Use
[diagnostics](/foliums/blueprintr-user-guide/foliums/diagnostics) for anything mechanical:
broken links, dangling redirects, missing descriptions, unknown icons. Reserve
automations for the judgement calls a rule cannot make.

Diagnostics with external link checking needs no agent. Internal links break
when someone deletes a page; external links break when the site at the other
end changes.

---

# Blueprintr User Guide: Export and print
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/export-and-print

> Getting content out as markdown for agents, a print-ready document, or the whole folium on disk.

## Markdown

Every page can be fetched as its source markdown, mainly for agents reading
your docs programmatically. Settings control how those exports are composed.

Content marked `[!VISIBILITY humans]` is stripped from the agent-facing
markdown, and `[!VISIBILITY agents]` content is stripped from the page a
person reads.

## Print

A folium can produce a print-optimised document covering the whole tree or a
subtree, with sensible page breaks, resolved links and diagrams rendered
inline.

> [!IMPORTANT]
> This is a print-ready HTML document that you print to PDF from your browser,
> not a server-generated PDF file. Use your browser's print dialogue and choose
> "Save as PDF". A server-side PDF would need a headless browser, which does
> not fit in the platform's serving constraints.

## The CLI

[`blueprintr-docs pull`](/foliums/blueprintr-user-guide/foliums/docs-cli) writes
the whole folium to disk as markdown files with frontmatter, and `push` uploads
them back.

---

# Blueprintr User Guide: Diagnostics
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/diagnostics

> The rule set that catches broken links, missing descriptions, bad icons and heading jumps.


Diagnostics check a folium against a fixed rule set. Run them from the manage
view, from an
[automation](/foliums/blueprintr-user-guide/foliums/automations), or offline
with the [CLI](/foliums/blueprintr-user-guide/foliums/docs-cli).

![A diagnostics run: 43 errors, 0 warnings, 0 suggestions, with the dangling-redirect findings listed under a card that names the stale path and what it now points at](/api/folium-assets/cmtozxvua0003ndrb3x90ioi2/raw)

## The rules

| Rule | Catches |
| --- | --- |
| `link-broken` | An internal link that resolves to no page |
| `link-draft` | A published page linking to a draft |
| `link-hidden` | A link to a page hidden from the nav |
| `redirect-dangling` | A redirect whose destination is gone |
| `redirect-loop` | Redirects pointing at each other |
| `duplicate-slug` | Two pages competing for one URL |
| `orphan-page` | A page nothing links to |
| `page-empty` | A page with no content |
| `page-oversized` | A page past the size ceiling |
| `missing-description` | No description, so previews fall back |
| `image-alt-missing` | An image with no alt text |
| `heading-jump` | A heading level skipped, which breaks the contents list |
| `icon-unknown` | An icon name that resolves to no glyph |
| `external-link-broken` | An off-site link that no longer responds |

## External links

External checking is off by default and only runs server-side. Probing an
author-supplied URL needs the platform's request guard, which refuses private,
link-local and metadata addresses. The CLI collects external links and lists
them but never fetches them.

## Links resolve like a browser

An internal link resolves against the page's URL the way a browser would. A
bare `sibling` written on the page `a/b` means `a/sibling`, not `a/b/sibling`.
Writing links as absolute in-app paths avoids the problem.

---

# Blueprintr User Guide: Folium analytics
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/folium-analytics

> Human and agent traffic, read depth, searches that found nothing, and six CSV exports.

**Manage → Documentation analytics**, over the last 7, 30 or 90 days. Every
panel exports as CSV: Traffic, Pages, Referrers, Searches, Assistant, Feedback.

## Traffic

| Metric | Is |
| --- | --- |
| Human views | Page reads that look like a person |
| Human visitors | Distinct sessions, counted approximately |
| AI / agent views | Reads by crawlers, bots and LLM agents |
| Total views | Both |

**Top pages** breaks the human/agent split down per page in two columns, and
*agent traffic by kind* separates ordinary crawlers from AI/LLM agents.

A page with heavy agent traffic and no human traffic is being read by machines
only. That is expected for reference material, and a signal if you wrote it
for people.

## Engagement

**Average read depth** across sessions: how far down the page readers get.
**Top outbound clicks** lists the destinations readers leave for, which
indicates what your documentation does not answer.

## Search

Searches, distinct terms, click-through rate, and zero-result searches. **Top
terms** shows each term with its CTR and the result readers picked.

**Searched, found nothing** lists each term and when it was last searched.

> [!TIP]
> A search with no result names a page a reader expected and did not find, in
> their own words. Review that list monthly and write the pages it names.

A term with searches and a 0% click-through means the page exists and its
title or description does not read as the answer.

## Assistant

Conversations and messages, broken down by the surface they came from, plus
recent conversations. What readers ask the
[assistant](/foliums/blueprintr-user-guide/foliums/docs-assistant) is the same demand
signal as a failed search, in full sentences.

## Page feedback

Helpful, not helpful, total responses and helpful rate, with the **lowest-rated
pages** for the window. Rating is independent of traffic, so a popular page can
sit near the bottom of that list.

## Your own measurement

**Manage → Analytics integrations** accepts GA4, PostHog (with a custom host),
Mixpanel and Segment ids, plus first-party click-heatmap sampling. Measurement
ids are public.

These mount on public and unlisted pages only. They are consent-gated, and are
never mounted on an
[embed](/foliums/blueprintr-user-guide/sharing/embedding-blueprints). An embed writes
nothing to the reader's device.

---

# Blueprintr User Guide: Docs CLI
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/docs-cli

> Write folium pages in your own editor, check them offline, and push when they are ready.


`blueprintr-docs` is a command-line tool for writing documentation in a text
editor instead of a browser.

> [!IMPORTANT]
> It is not published to npm and will not be. It ships inside the Blueprintr
> repository and is run from a checkout:
>
> ```bash
> node /path/to/blueprintr/cli/bin/blueprintr-docs.mjs --help
> ```

Its only dependencies are Node builtins, so there is no install step and
nothing to audit beyond the tool itself.

## Commands

| Command | Does |
| --- | --- |
| `validate [dir]` | Check local markdown. No network, no token |
| `pull <folium> [dir]` | Write a folium's pages to disk |
| `push <folium> [dir]` | Upload local markdown back |
| `open <folium> [path]` | Print and open the reader URL |

## Validate

```bash
blueprintr-docs validate ./docs --strict
```

`validate` makes no network calls and needs no credentials. It loads the
server's own diagnostics module rather than reimplementing the rules, so a
local pass and a server pass cannot disagree.

Exit codes are `0` clean, `1` findings, `2` bad command line, `3` credentials,
`4` network, `5` filesystem.

## Layout on disk

> [!TREE]
>
> - docs/
>   - folium.json
>   - index.md
>   - guides/
>     - index.md
>     - deploy.md

`folium.json` is optional and holds the slug, redirects, disabled rules and the
known icon list. A directory with no `index.md` still becomes a nav section.

## Pull and push

```bash
export BLUEPRINTR_TOKEN=bpk_user_…
blueprintr-docs pull handbook ./docs
```

Frontmatter holds the page `id`, and **that id is how `push` matches a file
to a page**. Editing or removing it makes `push` create a new page instead of
updating the existing one.

`push` never deletes a page. A page on the server but not on disk is reported
and left alone, so running the command in the wrong directory cannot cost you
a page. It never publishes a draft either: publishing stays an in-app action,
and `push` can retract a published page to draft but not the reverse. Link and
external pages are left untouched, because they point at something rather than
holding content.

## The token

`BLUEPRINTR_TOKEN` is a personal API key from **Dashboard → Settings →
Developer**. It is read from the environment and never from a flag, because
argv appears in `ps` and in shell history. Every line the tool prints is passed
through a redactor.

Organisation keys are rejected: they are read-only and scoped to public
documents.

## Links resolve like a browser

A page at `guides/index.md` has the URL `/guides`, so a relative `./aws/setup`
from that file resolves to `/aws/setup`, not `/guides/aws/setup`. Writing links
as absolute in-app paths (`/foliums/<slug>/guides/aws/setup`) avoids the
problem.

---

# Blueprintr User Guide: Migrating from another platform
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/foliums/migrating-from-another-platform

> Import a Docusaurus, GitBook, ReadMe, Fern or Document360 export into a folium, with a preview of the page tree first.

**Manage → Migrate from another platform** takes an export from an existing
documentation tool and turns it into folium pages.

| Source | |
| --- | --- |
| Docusaurus | |
| GitBook | |
| ReadMe | |
| Fern | |
| Document360 | |
| Markdown archive | Anything else: a directory of `.md` files |

Leave the source on **Detect automatically** unless it guesses wrong.

## What to upload

The export archive the other tool produces, as a `.zip` of up to **32 MB**. A
repository URL or a live site address is not accepted.

## Nothing is written until you say so

**Upload and preview** parses the archive and shows you the page tree it
intends to create. You approve it, and only then does anything land.

> [!IMPORTANT]
> A page the source marked hidden, unlisted or unpublished always arrives as a
> **draft**, whatever else the import does. A migration cannot publish
> something the old platform was holding back.

## After the import

> [!STEPS]
>
> === Run diagnostics
>
> [Diagnostics](/foliums/blueprintr-user-guide/foliums/diagnostics) catches what a
> migration reliably breaks: links that resolved under the old tool's URL
> scheme and do not under this one, headings that skip a level, images with no
> alt text, missing descriptions.
>
> === Rewrite internal links
>
> Internal links resolve **browser-style** against the page's own URL. A bare
> `sibling` on the page `a/b` means `a/sibling`. Exports from tools with a
> different resolution rule produce a lot of these; rewriting them as absolute
> in-app paths fixes the whole class at once.

## What does not come across

Anything that was a feature of the old platform rather than content: its
theming, its custom components, its redirects. List your existing redirects
before you migrate. A folium records a redirect when *it* moves a page, and
cannot inherit one from a tool it never ran.

## The other routes in

| You have | Use |
| --- | --- |
| An export from one of the tools above | This |
| Markdown in a Git repository | [Repo sync](/foliums/blueprintr-user-guide/foliums/repo-sync) |
| Markdown in a directory | [The CLI](/foliums/blueprintr-user-guide/foliums/docs-cli) |
| Pages in Confluence, Notion or SharePoint | [The import wizard](/foliums/blueprintr-user-guide/organise/importing-content) |
| An OpenAPI or AsyncAPI document | [API specs](/foliums/blueprintr-user-guide/foliums/api-reference-and-playground) |

---

# Blueprintr User Guide: Sharing
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing

> Visibility, embeds, link previews, custom domains, presenting, and your organisation's homepage.


How published content reaches readers: who can see it, how it appears
elsewhere, and where it is served from.

> [!TILES 3]
>
> === [The visibility model](/foliums/blueprintr-user-guide/sharing/visibility-model)
>
> Public, unlisted and private, and who can read each one.
>
> === [Embedding blueprints](/foliums/blueprintr-user-guide/sharing/embedding-blueprints)
>
> A live, interactive frame in someone else's page.
>
> === [Link previews and oEmbed](/foliums/blueprintr-user-guide/sharing/link-previews-and-oembed)
>
> What other tools show when your link is pasted.
>
> === [Subdomains and custom domains](/foliums/blueprintr-user-guide/sharing/subdomains-and-custom-domains)
>
> Publishing at your own address.
>
> === [Podium](/foliums/blueprintr-user-guide/sharing/podium)
>
> Present a diagram without exporting a deck.
>
> === [Atrium](/foliums/blueprintr-user-guide/sharing/atrium)
>
> Your organisation's front door.

---

# Blueprintr User Guide: Visibility model
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing/visibility-model

> Public, unlisted and private, who can read each one, and where organisation policy overrides your choice.

Visibility sets who may read a blueprint once it is published.

![blueprint:josh/visibility-model](https://blueprintr.io/embed/josh/visibility-model#h=520)

| Value | Who can read it | Search engines |
| --- | --- | --- |
| **Public** | Anyone | Indexed |
| **Unlisted** | Anyone with the link | Not indexed |
| **Private** | You, and anyone it is shared with | No |

## Unlisted links

An unlisted URL is unguessable, not protected. It survives being forwarded,
pasted into a ticket, or sitting in someone's browser history after they leave.

> [!IMPORTANT]
> Use private for anything that would matter if it leaked.

## Status comes first

An unpublished draft is invisible regardless of its visibility setting.
Visibility only takes effect once you publish.

## Organisation policy can override you

An organisation can apply a **classification** that caps how public its content
may be. Where a classification is set, you cannot publish above the ceiling it
defines, and the Publish step says so. See
[policies](/foliums/blueprintr-user-guide/teams/policies).

## Each surface gates independently

A blueprint's visibility does not automatically govern every route that can
reach its content. Files, embeds, discussion and analytics each apply their own
check. A mistake in one place cannot open all of them.

---

# Blueprintr User Guide: Embedding blueprints
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing/embedding-blueprints

> Put a live, interactive blueprint inside another page, whether your site, a folium, or someone else's wiki.

A published blueprint can be embedded elsewhere as a live, interactive frame.
Readers pan the diagram and open strata without leaving the host page.

## Getting the code

Use **Share → Embed** on a published blueprint. You get an `<iframe>` snippet.

The embed URL follows the blueprint's own address:

```
https://blueprintr.io/embed/<handle>/<slug>
```

## Sizing

The frame reports its own height to the host page, so it grows to fit its
content rather than scrolling inside a fixed box. Height and width can also be
pinned explicitly.

## Pinning a version

An embed can track the latest published version or be pinned to a specific one.
Pin it when the embed illustrates a point in time, such as a design as it stood
at a decision. Leave it tracking when it should stay current.

## What an embed does not do

> [!IMPORTANT]
> An embed writes **nothing** to the reader's device: no cookies, no local
> storage. Readers see no consent banner. Analytics for embedded views are
> aggregate and attributed to the embedding page.

Strata open as floating windows inside the frame rather than docking, because
there is no page to reflow.

## Visibility

Only public and unlisted blueprints can be embedded anonymously. A private
blueprint's embed requires the reader to be signed in and permitted, and
organisations can restrict embedding to an allow-list of hosts. See
[enterprise embeds](/foliums/blueprintr-user-guide/enterprise/enterprise-embeds).

---

# Blueprintr User Guide: Link previews and oEmbed
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing/link-previews-and-oembed

> What other tools show when someone pastes a Blueprintr link, and how to make it a live embed.

## Link previews

Paste a public blueprint's URL into a chat tool, a wiki or a social post and it
unfurls: title, description and a preview image of the diagram.

The preview image is generated from the blueprint itself, so it shows the
actual drawing rather than a generic card.

## oEmbed

Blueprintr is an oEmbed provider. Tools that support oEmbed can turn a pasted
link into a live, interactive embed rather than a static preview. It is the
same frame described in [embedding](/foliums/blueprintr-user-guide/sharing/embedding-blueprints),
with no iframe snippet to copy.

Support varies by tool. Where a tool does not recognise the provider, the link
falls back to an ordinary preview.

> [!NOTE]
> The embed URL is built from the **author's** handle. For an organisation
> blueprint that is not the same as the organisation's slug, so copy the URL
> from the Share panel rather than constructing it.

## Private content

Only public and unlisted content unfurls. A private blueprint's link shows
nothing beyond the URL. An unfurl in a chat channel would otherwise leak the
title to everyone in it.

---

# Blueprintr User Guide: Subdomains and custom domains
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing/subdomains-and-custom-domains

> Publishing an organisation's content at its own address rather than under blueprintr.io.


An organisation can serve its published content from its own address.

## Subdomain

Claim a label and the organisation's Atrium and folia are served from
`<label>.blueprintr.io`. This needs no DNS work.

The label is claimed once and becomes part of every URL underneath it.

## Custom domain

Point your own domain at Blueprintr instead. Add the domain in the
organisation's domains console and create the DNS records it shows you.
Verification is automatic once the records resolve, and certificates are issued
for you.

> [!IMPORTANT]
> A custom domain must be verified before it serves anything. Until then the
> content stays on the subdomain, and requests to the unverified domain are not
> answered.

## What moves

| Surface | Served from the custom domain |
| --- | --- |
| Atrium | Yes |
| Foliums | Yes |
| Published blueprints | Yes, for organisation-owned content |
| Personal blueprints | No, those stay under your handle |
| The dashboard and editor | No |

## Reader authentication

If you use
[reader authentication](/foliums/blueprintr-user-guide/foliums/reader-authentication),
the sign-in route must be reachable on the domain your folia are served from.
That is edge configuration rather than a setting; confirm it with whoever
operates the deployment before relying on it.

---

# Blueprintr User Guide: Podium
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing/podium

> Present a diagram as slides, with chapters, the pan-versus-morph rule, and the presenting keys.

A podium turns a Vellum diagram into a presentation. Each slide is a framed
region of the canvas; presenting pans and zooms between them.

The diagram stays the source. There is no export step, so the deck cannot drift
from the drawing.

## Slides and chapters

A slide is a view of the diagram rather than a copy. Editing the diagram
changes what the slide shows.

A chapter is a diagram tab. Slides belong to a chapter, and the audience walks
one flat sequence across every chapter in order: chapter one's slides, then
chapter two's, and so on. Reordering within a chapter reorders the talk;
reordering the tabs reorders the chapters.

The transition follows that structure:

| Moving | Looks like |
| --- | --- |
| Between slides in one chapter | A pan and zoom across the same canvas |
| Across a chapter boundary | A morph to the next diagram |

Put a change of subject in a new chapter, and keep one argument's slides in one
tab.

## Presenting

Present mode fills the screen. The keys:

| Key | Does |
| --- | --- |
| <kbd>→</kbd> / <kbd>Space</kbd> | Next slide |
| <kbd>←</kbd> | Previous slide |
| <kbd>PageDown</kbd> / <kbd>PageUp</kbd> | Next / previous |
| <kbd>Home</kbd> / <kbd>End</kbd> | First / last slide |

The pill shows the current slide's name, falling back to "Slide *n*" when you
have not named it. The chapter name is in the pill's tooltip rather than on the
pill itself.

The laser pointer (<kbd>L</kbd> in the editor) works here too.

## Strata as speaker material

A slide can show the strata attached to shapes in view, as cards beside the
diagram.

## Sharing

A podium is part of its blueprint and inherits its visibility. Anyone who can
read the blueprint can step through the podium.

> [!NOTE]
> The [Podium Recorder extension](/foliums/blueprintr-user-guide/sharing/browser-extension),
> which captures a flow in the browser and turns it into a deck, is on the
> roadmap and not yet installable. Build podiums from the diagram for now.

---

# Blueprintr User Guide: Podium Recorder extension
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing/browser-extension

> Capture a flow in the browser and turn each frame into a Podium slide. On the roadmap, with the app side already built.


> [!IMPORTANT]
> **Not shipped yet.** Podium Recorder is on the roadmap and is marked as such
> on [the download page](https://blueprintr.io/download). There is nothing to
> install in any extension store today. This page describes what it will do and
> what already exists behind it.

## What it is

A browser extension that records what you do in a tab and turns each captured
frame into a slide in a Blueprintr
[Podium](/foliums/blueprintr-user-guide/sharing/podium).

It is a **recorder**, not a presenter. Walking through a flow once produces the
deck; you present it afterwards from the podium itself.

- One-click frame capture
- Frames push straight into a Podium draft

## What already exists

The app-side contract is built and live. Frames upload directly to storage with
presigned URLs in an init → per-frame upload → finalize handshake. Image bytes
never pass through the API server.

Finalize is **idempotent**: retrying the same capture does not create a
duplicate tab.

| | |
| --- | ---: |
| Frames per session | 200 |
| Plan | Premium or above |

## Access

The extension will show only podiums you can already reach, and can only write
to a blueprint you can already edit.

## Presenting today

Until the recorder ships, build a podium the ordinary way, from a diagram's
slides in the editor, and present it from the browser. See
[Podium](/foliums/blueprintr-user-guide/sharing/podium).

---

# Blueprintr User Guide: Atrium
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/sharing/atrium

> An organisation's homepage, listing its blueprints, documentation and people, searchable in one place.

An Atrium is the front door to an organisation's content. One page listing what
the organisation has published, with search across all of it.

## What is on it

Configurable blocks: featured content, recently updated items, the
documentation sites the organisation runs, teams, and people. An organisation
can publish without an Atrium.

## Who can see it

The Atrium respects each item's own visibility. A visitor sees the public
subset; a member sees everything they have access to.

## Where it is served

At the organisation's subdomain, or its custom domain if one is configured. See
[subdomains and custom domains](/foliums/blueprintr-user-guide/sharing/subdomains-and-custom-domains).

## Search

Atrium search covers the titles and bodies of blueprints and folium pages,
scoped to the organisation.

---

# Blueprintr User Guide: Organise
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/organise

> Portfolios, search, bookmarks, importing and trash, for keeping a growing library findable.

Keeping things where you can find them.

> [!TILES 2]
>
> === [Portfolios and folders](/foliums/blueprintr-user-guide/organise/portfolios-and-folders)
>
> The folder model, and the Main portfolio you never create.
>
> === [Search and bookmarks](/foliums/blueprintr-user-guide/organise/search-and-bookmarks)
>
> Finding things, and keeping the ones you return to.
>
> === [Importing content](/foliums/blueprintr-user-guide/organise/importing-content)
>
> Confluence, Notion, SharePoint, or a folder of files.
>
> === [Trash and restore](/foliums/blueprintr-user-guide/organise/trash-and-restore)
>
> What a delete removes, and the thirty-day window to undo it.

---

# Blueprintr User Guide: Portfolios and folders
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/organise/portfolios-and-folders

> Folders for your content, including a Main portfolio you never have to create.


A portfolio is a folder. It holds blueprints, standalone diagrams, links and
notes, and it can hold other portfolios.

## Main

Every workspace has a **Main** portfolio, created automatically. Anything you
make without choosing a home lands there. It cannot be deleted.

## One home each

An item is in exactly one portfolio at a time. Filing is a move, not a copy.

> [!TIP]
> If you want the same blueprint to appear in two places, link to it from a
> note or embed it. Duplicating it means maintaining two.

## Ownership

A portfolio is owned by you, a team, or an organisation, the same three
owners as everything else. A portfolio's owner and its contents' owner are
independent: filing an organisation blueprint into a personal portfolio does
not make it yours.

## Nesting

Subfolders go as deep as you want. Two or three levels is usually enough.

## Links and notes

A portfolio can also hold plain links and short notes, so a folder can keep
the context around a set of blueprints: the ticket, the decision record, the
"read this first".

---

# Blueprintr User Guide: Search and bookmarks
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/organise/search-and-bookmarks

> Finding things across everything you can see, and keeping the ones you come back to.

## Search

<kbd>Cmd</kbd> <kbd>K</kbd> anywhere on the platform opens search. It covers
**titles and bodies** of the blueprints and folium pages you have access to, so
you can search for a phrase you remember rather than a title you do not.

You never see a result you could not open.

Official Blueprintr documentation is included in results, so a question about
the product itself is answered from the same box.

## Bookmarks

Bookmark anything you can read. Bookmarks are personal, sit under
**Dashboard → Bookmarks**, and survive the item moving between portfolios.

They are not a substitute for filing.

---

# Blueprintr User Guide: Importing content
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/organise/importing-content

> Bringing documentation in from Confluence, Notion, SharePoint or a folder of files.

The import wizard is at **Dashboard → Import**. Connect a source system, or
upload files.

![blueprint:josh/importing-existing-content](https://blueprintr.io/embed/josh/importing-existing-content?exclude=cmtpwbq6i000311r4hx5vzfcs&hideTabBar=1#h=620)

## Connecting a source

![The source picker: Files selected, with Confluence, SharePoint and Notion each badged "Requires setup"](/api/folium-assets/cmtozzfvk009pem4i6nwmznga/raw)

Confluence, Notion and SharePoint connect through a grant you authorise. You
then choose which spaces, databases or sites to bring across, and Blueprintr
converts pages into blueprints or folium pages.

Each shows a **Requires setup** badge until someone with admin rights has
configured the connection for the workspace. Files needs no setup.

> [!IMPORTANT]
> The grant is scoped to what you authorise, and it is per-source. Review what
> you are granting before confirming: an import writes into your
> organisation's content store.

## Uploading files

![The upload area, listing the accepted file types and their size ceilings](/api/folium-assets/cmtozzg4o009rem4ihxydlr1a/raw)

Drop files on the target or browse for them. Up to 200 files per import.

| Kind | Extensions | Ceiling each |
| --- | --- | --- |
| draw.io diagrams | `.drawio`, `.xml` | 5 MB |
| Documents | `.pdf`, `.docx`, `.pptx`, `.md`, `.txt` | 52.4 MB |
| Images | `.png`, `.jpg`, `.webp`, `.gif` | 21.0 MB |

## Diagrams

Imported diagrams are converted where the source format allows it. Anything
that cannot be converted comes across as an image, so the content is never
lost. Redraw it in [Vellum](/foliums/blueprintr-user-guide/vellum) afterwards.

## Watching a job

An import runs as a job with its own progress page. Large imports continue in
the background; you do not need to keep the tab open.

---

# Blueprintr User Guide: Trash and restore
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/organise/trash-and-restore

> A thirty-day recovery window, what a delete takes with it, and what permanent deletion removes for good.


Deleted items go to **Dashboard → Trash** rather than disappearing. Blueprints,
portfolios and Vellum saves all land there.

## The thirty-day window

Trash lists everything deleted in the last **30 days** that you can restore:
your own rows, plus team and organisation rows where you hold the role that
would let you restore them.

Items older than thirty days are listed separately, below, as a heads-up.

> [!IMPORTANT]
> Treat thirty days as the guarantee and nothing beyond it. Older rows are
> still recoverable today only because nothing purges them on a schedule yet.

## Restoring

Restoring puts an item back where it was. If its portfolio has since been
deleted, it returns to **Main**.

## What a delete takes with it

| Deleting | Also removes |
| --- | --- |
| A blueprint | Its strata, files and version history |
| A portfolio | **Nothing.** Its contents move up rather than being destroyed |
| A folium page | The redirects pointing at it |

A folder delete must never be a content delete, which is why a portfolio is the
exception.

> [!IMPORTANT]
> Deleting a page removes the redirects that pointed at it. Anything still
> linking to the old URL starts returning 404 rather than following a redirect
> to nothing. The `redirect-dangling` rule in
> [diagnostics](/foliums/blueprintr-user-guide/foliums/diagnostics) catches
> this.

## Permanent removal

**Permanently delete** on a row, or emptying trash, is exactly that. It is not
covered by version history and there is no second bucket behind it.

---

# Blueprintr User Guide: Teams
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams

> Organisations and teams, the two levels of shared work, and what belongs at each.

An **organisation** is the account: billing, domains, policy, and the people. A
**team** is a group inside it with its own members and its own content.

Bought a Teams licence? Start with
[Setting up an organisation](/foliums/blueprintr-user-guide/teams/setting-up-an-organisation).
The licence, the people and the teams all attach to one.

![blueprint:josh/teams-structure](https://blueprintr.io/embed/josh/teams-structure#h=520)

| | Organisation | Team |
| --- | --- | --- |
| Owns content | Yes | Yes |
| Has members and roles | Yes | Yes |
| Billing and licensing | Yes | No, inherits |
| Custom domain and Atrium | Yes | No |
| Policies and audit | Yes | Inherits, plus its own settings |

## When to add a team

Add one when a group needs its own content boundary: a different set of people
editing a different set of blueprints. Do not add one per project;
that is what [portfolios](/foliums/blueprintr-user-guide/organise/portfolios-and-folders)
are for, and they cost nothing to create.

## Built-in roles

Every membership has one of three built-in roles, and they are strictly
ordered: **owner > admin > member**.

| Role | Broadly |
| --- | --- |
| Owner | Everything, including billing and deleting the organisation |
| Admin | Everything operational, short of ownership |
| Member | Read and contribute according to what they are granted |

Owners and admins hold every permission implicitly. Members hold what their
[custom roles](/foliums/blueprintr-user-guide/teams/roles-and-permissions) grant.

> [!TILES 2]
>
> === [Setting up an organisation](/foliums/blueprintr-user-guide/teams/setting-up-an-organisation)
>
> Create it, license it, invite people, add a team.
>
> === [Members and invitations](/foliums/blueprintr-user-guide/teams/members-and-invitations)
>
> Getting people in, and out.
>
> === [Roles and permissions](/foliums/blueprintr-user-guide/teams/roles-and-permissions)
>
> The full permission catalogue.
>
> === [Policies](/foliums/blueprintr-user-guide/teams/policies)
>
> Rules that constrain what members may publish.

---

# Blueprintr User Guide: Setting up an organisation
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams/setting-up-an-organisation

> A Teams licence attaches to an organisation, so create that first. Then buy or attach the licence, invite people, and add a team.

A Teams licence belongs to an **organisation**, not to the person who pays for
it, so the organisation comes first: create it, license it, invite people, add
a team.

An organisation whose licence is not active is read-only. It refuses
invitations, new teams, subdomain changes, settings edits and publishing,
and each refusal says why. It still lets you buy the licence.

> [!STEPS]
>
> === Create the organisation
>
> **Dashboard → Settings → Teams & orgs → New organization**. The **Create
> new** menu has the same entry. Give it a name and a slug. The slug becomes
> its URL, `blueprintr.io/orgs/<slug>`. Description and website are optional.
> Creating an organisation is free, and you become its owner.
>
> === Buy the licence
>
> Open the organisation, choose **Settings**, then **Billing**. On the
> **Teams plan** card set **Seats**, then choose **Subscribe** for the monthly
> or the yearly plan. Checkout takes a card and your acceptance of the terms.
> Only the organisation's owners and admins can do this, and the seat count
> cannot be lower than its current membership. You count as one.
>
> The same controls are on **Dashboard → Licensing & Billing** under **Your
> organisations**.
>
> === Confirm the licence landed
>
> Payment returns you to the Billing page. Within a few seconds the Teams plan
> card changes from **No active plan** to the number of seats you bought.
> Refresh if it has not. **Plan & seats** and **License**, in the same
> settings, show seat usage and the licence history.
>
> === Invite people
>
> **Settings → Manage members → Invite by email**. Each member takes a seat,
> and a pending invitation reserves one until it is accepted, revoked or
> expires. Seats are changed from Licensing & Billing, not from the members
> page.
>
> === Add a team
>
> **Settings → Teams → New team**. A team has its own members and its own
> content, and inherits the organisation's licence. Add one when a group needs
> its own content boundary. Projects belong in
> [portfolios](/foliums/blueprintr-user-guide/organise/portfolios-and-folders)
> instead.

> [!NOTE]
> If you signed up from the **Team** plan on the pricing page, Blueprintr
> remembers that for a week. Finishing your profile takes you straight to
> **New organization**, creating the organisation opens its **Billing** page,
> and until a plan is active the dashboard shows a strip with the next step:
> **Create organisation** while you own none, or **Subscribe** for the
> organisation you already own.
>
> If Blueprintr granted your licence by hand rather than through Checkout, the
> dashboard shows a **You're licensed for Teams** strip with a **Create
> organisation** link instead. Create the organisation, then send support its
> slug. Support attaches the licence.

## After the licence

> [!TILES 3]
>
> === [Members and invitations](/foliums/blueprintr-user-guide/teams/members-and-invitations)
>
> Roles, seats, and what removing someone takes with it.
>
> === [Subdomains and custom domains](/foliums/blueprintr-user-guide/sharing/subdomains-and-custom-domains)
>
> Give the organisation its own address.
>
> === [Foliums](/foliums/blueprintr-user-guide/foliums)
>
> Documentation sites are organisation-owned and need the licence.

---

# Blueprintr User Guide: Members and invitations
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams/members-and-invitations

> Inviting people, what happens when they leave, and where seats are counted.


## Inviting

**Organisation → Settings → Manage members → Invite by email**. An invitation
is sent by email with the role you chose. It can be revoked before it is
accepted.

Inviting requires the `member.invite` permission. Owners and admins have it
implicitly.

## Seats

Members consume seats against your plan, and a pending invitation reserves a
seat until it is accepted, revoked or expires. The seat count and what is left
are on the organisation's **Plan & seats** page. Seats are changed from
[Licensing & Billing](/foliums/blueprintr-user-guide/account/billing-and-usage),
not from the members page.

An organisation with no active licence cannot invite anyone. See
[Setting up an organisation](/foliums/blueprintr-user-guide/teams/setting-up-an-organisation).

## Removing someone

Removing a member (`member.remove`) revokes their access immediately,
including anything derived from their membership, such as access to team
content and any custom roles they held.

> [!IMPORTANT]
> Content they authored stays with the organisation. Removing a person removes
> their access to it.

## Joining through SSO

Where [SSO](/foliums/blueprintr-user-guide/enterprise/single-sign-on) is configured, people
sign in through your identity provider instead of accepting an invitation. With
[SCIM](/foliums/blueprintr-user-guide/enterprise/scim-provisioning), membership is
provisioned and deprovisioned automatically from your directory.

---

# Blueprintr User Guide: Roles and permissions
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams/roles-and-permissions

> The full permission catalogue, and how custom roles combine with the built-in three.

Members keep their built-in role (owner, admin or member) **and** can hold
custom roles on top. A custom role is a named bundle of permissions.

Owners and admins short-circuit the check: they hold everything. Custom roles
are how you give a member a specific capability without making them an admin.

## The catalogue

### People

| Permission | Grants |
| --- | --- |
| `member.invite` | Invite members |
| `member.remove` | Remove members |
| `role.manage` | Manage custom roles |
| Assign custom roles | Give an existing role to a member |

### Content

| Permission | Grants |
| --- | --- |
| `blueprint.publish` | Publish blueprints |
| `blueprint.review` | Approve drafts |
| `blueprint.delete` | Delete blueprints |
| `atrium.edit` | Edit the Atrium |
| `folium.edit` | Edit foliums |

### Structure

| Permission | Grants |
| --- | --- |
| `team.create` | Create teams |
| `team.delete` | Delete teams |
| `policy.update` | Edit policies |

### Governance

| Permission | Grants |
| --- | --- |
| `audit.read` | Read the audit log |
| `license.read` | View plan and licence |

### Integrations and platform

| Permission | Grants |
| --- | --- |
| `webhook.manage` | Manage outbound webhooks |
| `integration.manage` | Manage Continuum integrations and cloud connections |
| `sso.manage` | Manage SSO |
| `scim.manage` | Manage SCIM provisioning |
| `network.manage` | Manage network access |

## Designing roles

> [!TIP]
> Build roles around jobs rather than people. "Docs maintainer"
> (`folium.edit` + `blueprint.publish`) survives someone changing team;
> "Sarah's permissions" does not.

Keep the count small. Every role is something a future admin has to understand
before they can safely change anything.

---

# Blueprintr User Guide: Policies
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams/policies

> Organisation-level rules that constrain what members can publish, and how public they can make it.

Policies are rules the organisation sets that individual members cannot
override. They are enforced at the point of publishing.

Editing them needs `policy.update`.

## Classification

A classification caps how public a piece of content may be. Where one applies,
the Publish step will not offer a visibility above the ceiling, and says why.

## Publish approval

Publishing can require a second person. Where it is on, publishing becomes a
submission and the content waits in
[Reviews](/foliums/blueprintr-user-guide/teams/reviews-and-approvals) for someone with
`blueprint.review` to approve.

The same setting exists per folium, so documentation can require approval while
blueprints do not, or the reverse.

## Where policy wins

> [!IMPORTANT]
> Policy always beats a member's choice. If a member sets a blueprint to public
> and a classification forbids it, the blueprint does not publish publicly. The
> conflict is reported at publish time with the reason.

---

# Blueprintr User Guide: Workflows
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams/workflows

> Multi-step approval and routing rules that run when content changes state.


A workflow is a named, enforceable sequence of steps that content moves
through, such as "this needs sign-off from two people, one of whom is in
security".

## Steps

Each step names who can act on it and what acting means: approve, reject, or
pass to the next step. Steps run in order, and content cannot skip one.

## Where a run starts

A run is created when the event a workflow is bound to happens, usually a
publish attempt. The content stays in its pre-publish state until the run
completes.

## Cancelling

A run can be cancelled, which returns the content to the author. Cancellation
is itself an authorised action.

> [!NOTE]
> Every step transition is recorded in the
> [audit log](/foliums/blueprintr-user-guide/teams/audit-log), including who acted
> and when.

## Workflows and policies

[Publish approval](/foliums/blueprintr-user-guide/teams/policies) is the
one-step case. Use a workflow when one approval is not enough: when the
approver depends on the content, or when several groups must sign in order.

---

# Blueprintr User Guide: Reviews and approvals
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams/reviews-and-approvals

> The review queue, the approve and reject decisions, and how multi-step workflows advance.


**Dashboard → Reviews** is the queue. It holds content submitted for approval
because a [policy](/foliums/blueprintr-user-guide/teams/policies) or a
[workflow](/foliums/blueprintr-user-guide/teams/workflows) requires it.

Acting on it needs `blueprint.review`.

## What an approver sees

The content as readers would see it, plus what changed since the last published
version. On a first publish there is no previous version, so all of it is the
change.

## Decisions

| Decision | Effect |
| --- | --- |
| Approve | Publishes, or advances to the next workflow step |
| Reject | Returns to the author with your comment, to edit and resubmit |

## Multi-step workflows

A workflow is an ordered list of steps, and a run sits on exactly one of them
at a time. Approving advances it; the run is only finished when the last step
approves.

Each step names its approvers two ways, and either is enough:

> [!FIELDS]
>
> > [!FIELD Named people|user ids|optional]
> >
> > Specific approvers for that step.
>
> > [!FIELD Roles|role ids|optional]
> >
> > Anyone holding one of these roles. Survives people joining and leaving, so
> > prefer it over naming individuals.

Only the **current** step's approvers can act. Being an approver on step three
does not let you approve step one.

> [!IMPORTANT]
> A workflow accepts runs only when it is **active** and has **at least one
> step**. An active workflow with no steps takes nothing. If authors report
> that submitting does nothing, check the step list first.

## Change requests are different

A [change request](/foliums/blueprintr-user-guide/blueprints/discussion-and-change-requests)
is a proposal from someone *without* edit rights. A review is a gate on someone
who *has* them. An author can withdraw their own change request, where only an
approver can resolve a review.

Documentation has its own version of this: a folium with
`requirePublishApproval` files a change request instead of publishing when a
non-admin publishes a version, and the
[REST API](/foliums/blueprintr-user-guide/developers/rest-api) answers
**202 Accepted** rather than an error.

---

# Blueprintr User Guide: Audit log
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/teams/audit-log

> Around 210 recorded actions, append-only at the database level, with IP addresses stored as hashes.

The audit log records consequential actions across the organisation. Reading it
needs `audit.read`.

## What is recorded

Roughly **210 distinct actions**, named `<target>.<what>` or
`<target>.<noun>.<verb>`: `blueprint.acl.revoke`, `blueprint.visibility.update`,
`apikey.revoke`, `enterprise.scim.deprovision`.

They hang off twenty-one target types:

`blueprint` · `user` · `team` · `org` · `invite` · `setting` · `portfolio` ·
`portfolio_folder` · `portfolio_item` · `diagram` · `vellum_save` · `comment` ·
`license` · `template` · `folium` · `integration` · `cloud_connection` ·
`continuum_integration` · `enterprise_tenant` · `lead` · `lead_company`

Each entry records who acted, what they acted on, when, a structured diff of
what changed, and enough request context to tell one session from another.

> [!NOTE]
> The diff is capped at about **4 KB**. A large change is summarised rather
> than captured whole.

## What it does not keep

> [!IMPORTANT]
> The log stores a **hash** of the IP address, never the address itself, along
> with the user agent. That is enough to tell two sessions apart or spot an
> anomaly, without building up a record of where members live.

## Append-only, and enforced twice

No codepath in the application updates or deletes an audit row.

> [!IMPORTANT]
> The database also installs triggers that **raise on `UPDATE` and `DELETE`**
> against the table. If a future refactor introduced a bypass, Postgres stops
> it. No owner, admin or support path can rewrite this log.

## Enterprise actions are catalogued

Action strings are free-typed except in the `enterprise.*` namespace.
Thirty-five constants cover tenancy, contracts, SSO, SCIM, IP allow-listing,
classification, white-label domains, integrations and stack provisioning, so an
enterprise event cannot be recorded under a name that differs from the one you
are searching for.

## Teams

Teams have their own audit view scoped to their own content, so a team lead can
review their area without being granted organisation-wide `audit.read`.

---

# Blueprintr User Guide: Enterprise
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/enterprise

> Directory-backed identity, network controls, embed governance and content connectors.


Enterprise features control who can sign in to an organisation and what happens
to its content.

| Feature | Answers |
| --- | --- |
| [SSO](/foliums/blueprintr-user-guide/enterprise/single-sign-on) | Who can sign in, decided by your identity provider |
| [SCIM](/foliums/blueprintr-user-guide/enterprise/scim-provisioning) | Who is a member, kept in step with your directory |
| [Network access](/foliums/blueprintr-user-guide/enterprise/network-access) | Where they can sign in from |
| [Embeds](/foliums/blueprintr-user-guide/enterprise/enterprise-embeds) | Which sites may frame your content |
| [Connectors](/foliums/blueprintr-user-guide/enterprise/content-connectors) | Which external systems content may be pulled from |

## Licensing

Enterprise features are enabled per organisation as part of a licence rather
than switched on from a settings page. Several also need provisioning on the
platform side.

Your organisation's current entitlement is on its licence page, visible to
anyone with `license.read`.

---

# Blueprintr User Guide: Single sign-on
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/enterprise/single-sign-on

> SAML and OIDC sign-in through your own identity provider.


SSO lets members sign in through your identity provider instead of holding a
Blueprintr password. Blueprintr supports Okta, Entra ID, Google Workspace and
any SAML 2.0 or OIDC provider.

Configuring it needs `sso.manage`.

![blueprint:josh/sso-vs-scim](https://blueprintr.io/embed/josh/sso-vs-scim#h=500)

> [!IMPORTANT]
> SSO is provisioned per organisation rather than self-served. Until it has
> been provisioned for yours, the SSO settings page reports that it is not yet
> available. Ask your account contact to enable it.

## What you will exchange

Setting up a connection is an exchange of metadata:

> [!STEPS]
>
> === Create the application in your IdP
>
> SAML 2.0 or OIDC, whichever you standardise on.
>
> === Give your IdP Blueprintr's endpoints
>
> The ACS URL and entity id, or the OIDC redirect URI, are shown on the SSO
> settings page.
>
> === Give Blueprintr your IdP's metadata
>
> The metadata URL or XML, or the OIDC issuer, client id and secret.
>
> === Test with one account
>
> Before you enforce it. Enforcing a misconfigured connection locks everyone
> out.

## Sign-in behaviour

Once connected, members sign in through your IdP. Whether that becomes the
*only* way in is a separate decision. Enforce it once you have confirmed a
working login and an owner who can still get in if the IdP is unavailable.

## Provisioning

SSO decides who may sign in.
[SCIM](/foliums/blueprintr-user-guide/enterprise/scim-provisioning) decides who
is a member and removes access when someone leaves your directory.

---

# Blueprintr User Guide: SCIM provisioning
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/enterprise/scim-provisioning

> Directory-driven membership, what it enforces, and the one-way group-to-role mapping.

SCIM keeps Blueprintr membership in step with your identity provider,
including deactivating people who leave. Configuring it needs `scim.manage`.

## SCIM and SSO

SSO controls authentication. SCIM controls **membership**. Without it, a person
removed from your directory keeps their Blueprintr membership until an admin
removes it by hand, and the seat stays billed.

> [!IMPORTANT]
> If you implement only one of SSO and SCIM and your concern is leavers,
> implement SCIM.

## How it flows

There is **no inbound public SCIM endpoint on Blueprintr**. Your IdP pushes
SCIM 2.0 to the SSO service, which normalises and stores it; Blueprintr then
*pulls* that directory state and projects it onto memberships and roles.

![blueprint:josh/how-scim-reaches-blueprintr](https://blueprintr.io/embed/josh/how-scim-reaches-blueprintr#h=520)

- The SCIM base URL and bearer token you configure in your IdP belong to the
  **SSO service** rather than to a Blueprintr API.
- Changes land when a **reconcile pass** runs, not the instant your IdP sends
  them. Real-time push is a future enhancement.

Each reconcile applies the cumulative effect of every event since the last one
*and* diffs directory state against local state, so it doubles as drift
detection. The delta is audited.

## What is enforced

| | |
| --- | --- |
| Membership | Created on first sight |
| Deactivation | An IdP deactivate suspends or removes the member |

## What is not enforced

Group-to-role mapping is **additive and one-way**:

> [!IMPORTANT]
> Removing someone from a directory group does **not** remove the Blueprintr
> role it granted. SCIM never downgrades a role automatically, and never
> assigns organisation **owner**.

One-way mapping stops SCIM undoing a role an admin granted by hand, and stops
a mis-scoped IdP group locking an organisation out of its own tenancy.

Drift in the unenforced direction is **reported in the run summary** rather
than acted on. Read those summaries: a role someone should no longer hold
shows up there.

> [!NOTE]
> If directory groups are unavailable during a run, membership still
> reconciles and group-to-role sync is skipped for that pass. The summary says
> so.

## Setting it up

Configure the directory in **Organisation settings → Enterprise → SCIM**. The
page is unavailable unless enterprise SSO is enabled for the deployment and the
SSO service is reachable. A greyed-out page is a platform prerequisite rather
than a permission problem.

The token is shown once. Store it in your IdP immediately. Regenerating
invalidates the old one.

## Auditing

Every SCIM operation writes an [audit](/foliums/blueprintr-user-guide/teams/audit-log)
entry under its own action: configure, provision, deprovision, reconcile,
rotate, toggle and delete. A membership that changed because of your directory
is distinguishable from one an admin changed by hand.

---

# Blueprintr User Guide: Network access
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/enterprise/network-access

> Restricting where members can reach your organisation's content from.

Network access rules limit which source addresses may reach your organisation's
content. Configuring them needs `network.manage`.

## How rules apply

Rules are evaluated per request against the caller's address. A request from
outside the permitted set is refused before it reaches any content.

> [!IMPORTANT]
> Lock yourself out and you will need support to get back in. Before enforcing
> a rule, confirm the address range you are adding covers the way you connect,
> including from home and whatever your VPN egresses as.

## Coverage

Network rules govern access to your organisation's content. They do not apply
to published public content: a blueprint you have made public stays reachable
regardless of the rule.

To restrict who reads documentation, use visibility and
[reader authentication](/foliums/blueprintr-user-guide/foliums/reader-authentication)
rather than network rules.

## Client addresses

The address a rule is evaluated against is determined at the platform edge, not
taken from a request header.

---

# Blueprintr User Guide: Enterprise embeds
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/enterprise/enterprise-embeds

> Controlling which external sites may frame your organisation's content.

By default a public blueprint can be embedded anywhere. An organisation can
narrow that to an allow-list of hosts.

Managing it needs `integration.manage`.

## Allow-listing

Add the hosts permitted to frame your content. A request to embed from anywhere
else is refused, and the frame stays empty rather than rendering.

Use it for public content, such as a reference architecture or a standard, that
you want read in context rather than embedded in somebody else's product.

## Authenticated embeds

Private content can be embedded on a permitted host with the reader
authenticating first. The reader signs in, and the embed then resolves against
what that person may see.

> [!NOTE]
> Embeds write nothing to the reader's device on any surface. Authenticated
> embeds use their own short-lived session rather than reusing a cookie the
> embed surface never sets.

---

# Blueprintr User Guide: Content connectors
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/enterprise/content-connectors

> Pulling content into a blueprint from Confluence, Notion or SharePoint, live rather than copied.


A connector links your organisation to an external content system. Once
connected, a blueprint tab can render content from it in place, rather than
holding a copy that drifts.

Managing connectors needs `integration.manage`.

## Source-embed tabs

A **source embed** tab names a page in the connected system. Blueprintr fetches
it when the blueprint is read, using the viewer's own permission in the source
system.

> [!IMPORTANT]
> A source embed resolves per viewer, with that viewer's access. Someone who
> cannot read the Confluence page cannot read it through Blueprintr either. The
> content is never cached into a surface with different permissions.

Because it is a per-viewer privileged fetch, source-embed tabs do not render on
anonymous surfaces: marketing pages, public embeds, or a frozen version
snapshot. Those show an inert reference card instead.

## Import versus connect

![blueprint:josh/import-vs-connect](https://blueprintr.io/embed/josh/import-vs-connect#h=500)

[Importing](/foliums/blueprintr-user-guide/organise/importing-content) copies
content in once and it becomes yours. A connector leaves the content where it
is and renders it live. Import when you are migrating; connect when the other
system stays the source of truth.

---

# Blueprintr User Guide: Continuum
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum

> Connect a diagram to live infrastructure, so the drawing can be checked against what exists.

Continuum connects a diagram to the systems it describes, so the drawing can be
regenerated and the detail on it comes from the source.

## Two products, two licences

| | **Continuum Cloud** | **Continuum Link** |
| --- | --- | --- |
| Connects to | AWS and Azure. Terraform state adds drift on AWS connections only | 29 platforms directly, 10 more through the local agent |
| Puts live data on strata | Yes | Yes |
| **Draws on the canvas** | **Yes** | **No, never** |
| Licence | Teams | Enterprise |
| Permission | `cloud_connections.manage` | `continuum_integrations.manage` |

> [!IMPORTANT]
> Continuum Link cannot draw. It brings live data from another platform onto a
> stratum. To generate a diagram from your infrastructure, use Continuum Cloud.

Both are set up in the same place, **Settings → Continuum** on an organisation or
a team. In the blueprint editor the menu that offers both is headed "Continuum
Link", which is a leftover from when the two shared a name. The row labelled
**Continuum** is the Cloud one.

## The Cloud pipeline

> [!STEPS]
>
> === Connect an account
>
> A read-only connection to an AWS account or an Azure subscription.
>
> === Choose the scopes
>
> Which accounts or subscriptions, and which regions, this diagram covers.
>
> === Sync
>
> Continuum reads the estate once, on demand, and records what it found as a poll
> run.
>
> === Draw and attach
>
> Resources become shapes on a Vellum canvas, and every resource gets a stratum.

> [!TILES 3]
>
> === [Continuum Cloud](/foliums/blueprintr-user-guide/continuum/continuum-cloud)
>
> Drawing an AWS or Azure estate inside a blueprint.
>
> === [Cloud connections](/foliums/blueprintr-user-guide/continuum/cloud-connections)
>
> Granting read-only access to AWS, Azure or Terraform state.
>
> === [Scopes and syncing](/foliums/blueprintr-user-guide/continuum/scopes-and-polling)
>
> Choosing what a diagram covers, and running the sync that builds it.
>
> === [Keeping diagrams true](/foliums/blueprintr-user-guide/continuum/keeping-diagrams-true)
>
> What a sync preserves, and what the shape outlines mean.
>
> === [Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link)
>
> Attaching operational data from another platform to a stratum.
>
> === [Connector reference](/foliums/blueprintr-user-guide/continuum/connector-reference)
>
> All 39 connectors, what each asks for and what each shows.
>
> === [Alerts on a diagram](/foliums/blueprintr-user-guide/continuum/alerting)
>
> Where alert state appears, and where it does not.
>
> === [Continuum Local](/foliums/blueprintr-user-guide/continuum/local-agent)
>
> The on-premise agent for systems Blueprintr cannot reach.

---

# Blueprintr User Guide: Continuum Cloud
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/continuum-cloud

> Draw a live AWS or Azure estate as a managed diagram inside a blueprint, and attach every resource's detail to it.

Continuum Cloud reads a live AWS account or Azure subscription and draws it as a
Vellum diagram inside a blueprint. Every discovered resource also gets a stratum
holding its configuration, so the drawing and the detail behind it both come
from the source.

It needs a Teams plan or above, and `cloud_connections.manage` on the
organisation or team that owns the connection. Below Teams, creating a
connection refuses with "Continuum is a Teams-plan feature."

## What it produces

One Continuum tab in a blueprint, backed by a private Vellum document named
after the tab. Alongside it:

| Artefact | What it holds |
| --- | --- |
| Shapes on a canvas | Resources the layout draws, nested inside the boundaries that exist in the source |
| A stratum per resource | Identity, configuration, per-type tables, tags, related strata, and the raw payload in a collapsed **Raw data** disclosure |
| A poll run per scope, per sync | What was found, what changed, and every read that failed |

> [!IMPORTANT]
> A stratum is a blueprint file, so it follows the blueprint's own visibility. On
> a public blueprint, anonymous readers see every discovered resource's account
> id, resource id, region, addresses and the **Raw data** payload. Review what a
> Continuum diagram carries before publishing it publicly.

Resources that describe relationships rather than occupy space, such as route
tables, security groups, network ACLs, IAM and KMS, get a stratum with no shape.
They are filed under a **(Context)** folder in the Files sidebar and cross-linked
from the resources they affect.

A resource collapsed into a group shape, such as Auto Scaling members or a Lambda
name family, also gets a stratum with no shape of its own. Those sit alongside the
drawn resources rather than under **(Context)**.

## Building one

> [!STEPS]
>
> === Connect a cloud account
>
> Open **Settings → Continuum** on the organisation or team and add an AWS or
> Azure connection. Terraform state is not a connection of its own: add a cloud
> connection first, then set its **Terraform backend**. See
> [cloud connections](/foliums/blueprintr-user-guide/continuum/cloud-connections).
>
> === Add a Continuum tab
>
> Give the blueprint a title, then choose **Continuum** from the editor's
> **+ Add tab** menu. Below Teams the row is disabled and reads "Teams plan
> required".
>
> === Choose the scopes
>
> Pick the connection, name the tab, then select accounts or subscriptions and
> regions. See
> [scopes and syncing](/foliums/blueprintr-user-guide/continuum/scopes-and-polling).
>
> === Create
>
> Blueprintr discovers each scope, draws the diagram, mints the strata and saves.
> The tab opens on the finished canvas.

## What is discovered

Continuum discovers 77 AWS resource types and 75 Azure resource types. Of those,
53 AWS types and 52 Azure types are drawn as shapes by default. The rest are
read for their relationships, for the containers they define, or for stratum
context.

> [!NOTE]
> A scope narrows by place and by tag, never by service. There is no
> resource-type picker.

## Views on the same canvas

The canvas carries a **View** switcher. Base topology is the default; the others
recolour the same shapes to answer one question each: Routing, Security groups,
Cost (est.), IP addresses, Public exposure, Availability zone and Tag coverage.
Views authored on the diagram appear in the same list.

## Keeping it current

Syncing is manual on every plan. Open the tab's settings cog and choose
**Sync now** to re-discover every scope, or **Re-sync** one scope from
**Settings…**. A sync preserves the canvas you saved and reports its result as
"Synced, +3 added, 1 changed, 0 missing."

Scheduled syncing is not available. Choosing a cadence under **Auto-sync**
returns "Scheduled polling is not available yet - Continuum runs one-time
scans." That is not a plan gate, and no upgrade lifts it.

[Keeping diagrams true](/foliums/blueprintr-user-guide/continuum/keeping-diagrams-true)
covers what a refresh preserves, what the shape outlines mean, and how newly
discovered resources are promoted onto the diagram.

## Binding one shape instead

A shape you drew yourself can be bound to a single live resource without
generating a whole diagram. Add a stratum to it, open **+ Add tab** and choose
**Continuum**. AWS and Azure connections can both be bound. A Terraform-state
connection cannot, because a state snapshot has no live resource to re-read.

## Continuum Cloud is not Continuum Link

Continuum Cloud draws. [Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link)
brings operational data from monitoring, on-call and ITSM platforms onto a
stratum and never touches a canvas. They are separate products on separate
licences, and the editor menu that offers both is headed "Continuum Link" for
historical reasons.

---

# Blueprintr User Guide: Cloud connections
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/cloud-connections

> Giving Continuum read-only access to an AWS account or Azure subscription, with credentials you control.

A cloud connection is the read-only credential
[Continuum Cloud](/foliums/blueprintr-user-guide/continuum/continuum-cloud) uses
to discover your estate. Create one from **Settings → Continuum** on an
organisation or a team.

You need `cloud_connections.manage` on that organisation or team, and a Teams
plan or above. Below Teams the action refuses with "Continuum is a Teams-plan
feature." Without any integrations permission the page returns a 404 rather than
telling you the organisation exists.

Teams allows three connections per owner. Reaching the cap refuses with
"Connection cap reached (3 per org)", or "(3 per team)", naming whichever owns
it. Blueprintr first reclaims your own drafts that have sat untouched for a day
with no credential of any kind and nothing referencing them. Drafts created by
someone else, and your own from the last 24 hours, are left alone, so the cap can
still refuse. Enterprise has no cap.

## Read-only, always

> [!IMPORTANT]
> Continuum never writes to your cloud account. The permissions it asks for list
> and describe. If you are reviewing the grant, anything that mutates
> infrastructure is out of scope and should be refused.

## AWS

The first step asks for your own 12-digit **AWS account number**, not for
anything to copy back. Blueprintr then offers a prepared CloudFormation template
through **Launch in AWS**, creates a read-only role, and watches for it to
appear. If the CloudFormation form asks for an **External ID**, paste the one
shown beside the launch button; the current template fills it in already. The
external ID is what stops another tenant assuming your role.

If the watch times out, a collapsed panel lets you paste the role ARN yourself.

### Choose the scope of the grant first

**Connection scope** offers two modes. It stays changeable while the connection
is a draft, by going Back in the wizard. Once a role has been recorded
it is fixed: "This connection already has a role, so its scope can't be changed.
Create a new connection instead."

| Mode | What it creates | Use it for |
| --- | --- | --- |
| **Single account** | One read-only role in one account | One account you want to draw |
| **AWS Organization** | A role to enumerate accounts, plus a StackSet that places a member role in every account, including accounts created later | Control Tower, Landing Zone and other multi-account estates |

Organization mode is run from the management or delegated-admin account and needs
trusted access between AWS Organizations and CloudFormation StackSets, which is
enabled once per organisation. A single-account role cannot serve an
organisation-mode connection, and the mismatch fails at inventory time rather
than at creation.

## Azure

Register an Entra application, create a client secret on it, and grant it the
built-in **Reader** role on the subscriptions you want visible. Paste back the
**Directory (tenant) ID**, the **Application (client) ID** and the **Client
secret value**, which is the value rather than the secret id, and which Azure
shows once. Where policy forbids built-in Reader, the wizard offers a narrower
custom role definition to create instead.

An Azure connection authenticates with a client secret. Workload identity
federation is not available, so the wizard has no **Federation** option.

You create the secret in Azure. The copy-and-run script the wizard offers creates
it with a two-year life; the portal click-path leaves Azure's own default, so
check it. Blueprintr encrypts it at rest and never returns it to the browser.
Replace it later from the connection's detail page rather than by rebuilding the
connection.

One Azure connection covers a set of subscriptions. A connection whose app
registration has no Reader grant fails verification outright: "The connection
authenticated but no subscriptions are visible to it. Assign the Reader role at
subscription scope." Grant Reader, then verify again.

## Google Cloud

Continuum Cloud does not discover Google Cloud, and the wizard offers AWS and
Azure only. Google Cloud Monitoring is available as a
[Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link)
connector, which attaches alerting policies to shapes you draw yourself.

## Terraform state

Terraform is not an alternative to granting access. Add a cloud connection first,
then set a backend on that connection's detail page under **Terraform backend**.
Continuum reconciles what you declared against what discovery found, and outlines
a resource whose live configuration has diverged from state in amber.

> [!IMPORTANT]
> Drift reconciliation works on AWS connections only. The backend form is not
> provider-gated, so an Azure connection accepts a backend and returns nothing
> from it.

For **S3 remote state**, give the bucket, object key and bucket region, and add
`s3:GetObject` on the state object to the Continuum role policy. The template role
cannot read bucket contents on its own.

For **Terraform Cloud**, give the workspace id and a workspace-scoped token with
`state:read`. Saving without one is refused: "A workspace token is required when
switching to Terraform Cloud."

A Terraform-source connection cannot back a single bound shape, because a state
snapshot has no live resource to re-read.

## Verifying

**Verify** re-proves the credential: an assume-role and identity check for AWS, a
token plus subscription and resource-group read for Azure, and a fetch and parse
for Terraform state. Discovery only runs on a connection that has verified, so
verify after any credential change.

## Regions and deletion

Regions are fixed when you create the connection: one region in single-account
mode, a set of regions in AWS Organization mode. There is no region control on
the connection afterwards, so covering a new region means a new connection.

Which of those regions a particular diagram uses is a separate choice, made per
diagram under
[scopes](/foliums/blueprintr-user-guide/continuum/scopes-and-polling).

Deleting a connection is refused while an integration or scope still references
it: "Connection is in use by N integration(s) and M scope(s). Remove those
first." A shape bound to the connection, or a Continuum Link connector borrowing
its role, also blocks the delete, so unbind those too.

---

# Blueprintr User Guide: Scopes and syncing
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/scopes-and-polling

> Choosing what a Continuum diagram covers, and running the sync that builds it.

A **scope** is what one Continuum diagram covers. On AWS it is one account paired
with one region. On Azure it is one subscription paired with one location.

A diagram can carry several, but they must all come from the same provider.
Adding an Azure scope to an AWS tab is refused: "This Continuum tab was created
from a different cloud provider. Add the scope to its own Continuum tab
instead."

## Choosing scopes

Pick accounts or subscriptions, then regions. Every combination becomes its own
scope, so three accounts and two regions is six scopes. The picker shows the
running total.

These optional narrowings apply on top:

| Control | Provider | Default |
| --- | --- | --- |
| **Refine VPCs / subnets** | AWS | Every VPC in the scope |
| **Refine resource groups** | Azure | The whole subscription |
| **Tag filter** | Both | No filter |

A resource is imported when every tag listed matches. The filter applies to all
selected scopes.

> [!IMPORTANT]
> The tag filter fails open. A resource whose payload carries no tag data is
> imported anyway, so untagged resources, and resources whose list API returns no
> tags at all such as route tables and log groups, still appear. EC2 instances are
> the exception, because AWS filters them server-side, so an untagged instance is
> dropped. Do not use the tag filter to keep anything out of a shared diagram.

> [!NOTE]
> There is no resource-type picker. Continuum discovers the types it supports and
> you narrow by place and by tag, not by service.

> [!TIP]
> Scope to the thing you are explaining, not to the account. An unscoped account
> produces a diagram of everything in it, which nobody can read.

One commit fans out to at most 12 scopes on AWS and 4 on Azure, and the picker
says so when you go over.

On Teams the plan cap of three scopes per diagram bites first, and the picker does
not know your plan. A selection of four or more still shows as valid and the
server refuses it after you press create. Narrow the selection, or add the rest as
extra scopes afterwards.

## Adding, re-syncing and removing scopes

Open the Continuum tab's settings cog and choose **Settings…**. Each scope has
**Re-sync**, and **+ Add another scope** adds more.

Every control here needs edit access on the blueprint plus `cloud_connections.manage`
on each scope's connection. Without the permission the buttons do not appear.

> [!IMPORTANT]
> **Remove** drops that scope's resources from the diagram and deletes the strata
> attached to them. Other scopes are untouched, and the deletion cannot be undone.
> The confirmation dialog says so.

**Remove** is disabled on the last remaining scope: "Cannot remove the last
scope. Delete the Continuum tab instead."

## Syncing is manual

**Sync now** from the cog re-discovers every scope and reports the result, for
example "Synced, +3 added, 1 changed, 0 missing."

> [!IMPORTANT]
> Scheduled syncing does not work on any plan. The **Auto-sync** picker offers
> Off, Every 1h, 4h, 12h and 24h, but choosing any cadence returns "Scheduled
> polling is not available yet - Continuum runs one-time scans." That is not a
> plan gate and no upgrade lifts it. Turning it Off is always accepted.

## Reading a sync

Each scope's discovery is recorded as its own **Poll run**, reachable from the
history list in **Settings…**, so one **Sync now** across three scopes produces
three runs. Removing a scope writes one too.

A run reports what it found, what changed since the last one, and an **Adapter
errors** section listing every read that failed.

Check that section before concluding something was decommissioned. A permission
error produces a smaller diagram with an explanation, not a silent gap. Once the
permission is fixed, choose **Sync now** again.

The ten most recent runs are listed. There is no view that compares two runs side
by side.

## Limits

Continuum Cloud caps, enforced:

| | Team | Enterprise |
| --- | ---: | ---: |
| Cloud connections per owner | 3 | Unlimited |
| Scopes per diagram | 3 | Unlimited |

Continuum Link caps, enforced:

| | Team | Enterprise |
| --- | ---: | ---: |
| Connections per owner | 5 | Unlimited |
| Linked tabs per stratum | 8 | 20 |
| Identifiers per blueprint scan | 200 | 200 |

Continuum Link needs Enterprise, so its Team column applies only where an
Enterprise entitlement has lapsed.

**Team settings → Plan & limits** also shows **Resources per integration** as 200
on Teams and unlimited on Enterprise. Nothing enforces that figure, and a sync
is not truncated at 200 resources. The same card shows **Scheduled polling**
as "Scan only" on both tiers.

---

# Blueprintr User Guide: Keeping diagrams true
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/keeping-diagrams-true

> What a sync preserves, what the shape outlines mean, and how new resources reach the diagram.

![A Continuum diagram divided into the parts Continuum manages and the parts you author, with arrows showing which side a refresh may change](https://blueprintr.io/embed/josh/continuum-managed-vs-yours#h=520)

Once a scope has been discovered, Continuum puts the results on a canvas and
mints a stratum for every resource it found.

## Shapes and strata

Resources the layout draws become shapes, nested inside the boundaries that exist
in the source: accounts, regions, VPCs and subnets, resource groups.

Resources that describe relationships rather than occupy space get a stratum with
no shape. Route tables, security groups, network ACLs, IAM and KMS are filed
under a **(Context)** folder in the Files sidebar and cross-linked from the
resources they affect.

A resource collapsed into a group shape, such as Auto Scaling members or a Lambda
name family, also gets a stratum with no shape of its own. Those sit alongside the
drawn resources rather than under **(Context)**.

A Continuum stratum's body tab is labelled **Continuum** rather than Overview. It
holds a Resource table, a Details table, per-type tables, Tags, links to related
strata, and the full payload in a collapsed **Raw data** disclosure. A Terraform
drift tab joins it where state is reconciled.

## What a sync preserves

> [!IMPORTANT]
> After the first draw, the canvas you saved is the authority on geometry. Your
> positions, sizes, labels, styling, groups, notes and connector routes are kept.
> Only new shapes are laid out.

Containers can grow to make room for additions without moving what is already
inside them. Where a container is boxed in by authored content, Continuum places
the addition in free canvas space and keeps its resource membership rather than
moving your work.

A label or membership you have not customised follows the source. Anything you
overrode wins. Managed shapes you deleted stay deleted once the diagram has
recorded a refresh baseline. Older diagrams without that baseline preserve
customisations conservatively, because a deletion made before the baseline cannot
always be inferred.

## New resources wait for you

A resource discovered after the first sync is not added to the diagram straight
away. It is drawn on the notes layer with a green outline, and the settings cog's menu
shows a running delta such as "+3 new".

Choose **Promote N new resources** from the cog to move them onto the blueprint
layer. Until then they sit alongside the diagram rather than in it.

## What the outlines mean

| Outline | Meaning |
| --- | --- |
| Default | Active |
| Red | The source reports the resource offline |
| Dashed grey | Pending removal |
| Red solid, on the notes layer | Removal confirmed |
| Red dashed, on the notes layer | Referenced from outside the scopes you sync, labelled "out of scope" |
| Yellow dashed, on the notes layer | In Terraform state but not found in the cloud, labelled "in tf, not in aws" |
| Green, on the notes layer | Newly discovered, awaiting promotion |
| Amber | Live configuration has drifted from Terraform state |

Drift takes precedence over lifecycle. These outlines come from cloud discovery
only. A linked monitoring platform never changes a shape.

## Changing the reading direction

Reading direction is not a control on the tab. Ask the AI assistant to reorder the
diagram top down or left to right. It proposes the change and applies it only
after you confirm.

> [!IMPORTANT]
> Confirming lays out every managed shape again and discards the positions you
> moved them to. No other action on this page does. Ordinary syncing,
> additions and promotion all preserve your layout.

## Version restore is refused

Once a blueprint carries Continuum-managed content, restoring an older version of
it is refused. A version snapshot never captured the connections and bindings
behind those tabs and strata, so a restore would delete them with nothing to
rebuild from. Remove the Continuum component and unbind those strata first. See
[versions and history](/foliums/blueprintr-user-guide/blueprints/versions-and-history).

## Binding one shape instead

A shape you drew yourself can be tied to a single live resource. Add a stratum to
it, open **+ Add tab** and choose **Continuum**, then pick a connection, a region
or location, and one resource. **Pull now** re-reads it.

AWS and Azure connections can both be bound. A Terraform-state connection cannot:
"Only AWS and Azure connections can back a live stratum."

The control appears only for a signed-in editor on a Teams plan or above, on a
rich stratum in a saved blueprint. Binding also needs `cloud_connections.manage`
on the organisation or team that owns the connection; without it the picker
reports no usable connections. Readers never see it.

---

# Blueprintr User Guide: Continuum Link
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/continuum-link

> Attach a dated snapshot from a monitoring, on-call or ITSM platform to the stratum that explains it.

Continuum Link attaches a saved snapshot from an operational platform to a
stratum, as its own read-only tab. Alert state, service ownership and change
context sit beside the thing on the diagram they refer to.

It needs an Enterprise plan, edit access to the blueprint, and
`continuum_integrations.manage` on the organisation or team that owns the
connection. Below Enterprise the engine refuses with "Continuum integrations
are an Enterprise feature."

## It never draws

> [!IMPORTANT]
> Link writes to a stratum tab and nowhere else. It cannot add, move, recolour
> or delete anything on a canvas. Diagrams generated from infrastructure come
> from [Continuum Cloud](/foliums/blueprintr-user-guide/continuum/continuum-cloud).

## Connect a platform

Open **Settings → Continuum** on the organisation or team, find
**Operational integrations**, and choose **New integration**. The form asks for
a **Type**, a **Name**, whatever non-secret fields that connector declares, and
one credential. Choosing **Connect & verify** stores the credential and runs a
handshake against the platform in one step.

Jira Cloud and Jira Service Management Operations replace that button with
**Connect with Atlassian** and sign you in instead. Most other connectors take a
pasted token or key, GitHub and GitLab included.

Two groups store no credential here. AWS CloudWatch reuses a verified AWS cloud
connection: pick that connection and a region, and widen its role with the
CloudWatch and Logs actions the form lists. The ten on-premise connectors keep
their credential on the Continuum Local agent, and Blueprintr never stores it.

Credentials are encrypted at rest, are never returned to the browser, and are
never written into a snapshot. The row afterwards shows a verification state and
a bound-tab count.

## Link an object to a stratum

Save the blueprint, open a stratum, and choose **Continuum Link** from its
**+ Add tab** menu. Search across every verified connection you can use, review
the candidate's identity, then select **Link object**. The first snapshot is
fetched before the binding is saved, so a link that would have failed never
lands.

One connection holds one linked object per stratum. Selecting a different object
from the same connection replaces that connection's binding. A stratum can carry
20 linked tabs; a twenty-first is refused with "This stratum already has the
maximum of 20 integration tabs." Linked tabs do not count toward the 20 tabs you
add to a stratum yourself.

In the blueprint editor a linked tab is read-only, because each re-fetch replaces
its content. It can still be renamed. To delete it, remove its link.

These tools propose candidates instead of you searching:

| Tool | Where | What it checks |
| --- | --- | --- |
| **Suggest Continuum Links** | A stratum's tab strip | Blueprintr's [suggestion index](#the-suggestion-index) of every connection, for objects matching the stratum's linked shape, its title, and hostnames, addresses or URLs in its text. **Check live** asks the connections themselves |
| **Suggest Continuum Links** | Under a Vellum diagram's bottom bar | The same index, for every shape on the blueprint's saved diagrams, including Continuum Cloud canvas shapes that already have a stratum. **Check live** asks the connections the index does not fully cover |
| **Suggest integrations…** | A shape's right-click menu | Up to six connections, for that shape's own identifiers |
| **Scan for integrations** | Resources & Strata | Titles, tab bodies, file content and diagram shape labels, up to 200 identifiers per scan |

**Suggest Continuum Links** lists every match it finds and ticks one for you only
when its evidence is strong on its own and nothing competes for it. No second
object from the same connection can match as closely, no other shape can claim
the same object, and the shape's icon must not show a different kind of system.
Nothing is ticked from a connection that failed for some shapes, from one whose
index is out of date, incomplete or limited to some object types, or when a run finds more matches than it can
compare, because a competing match could be missing. It never searches for a name that only describes a role, such as
"Database" or "Web server", and it skips container names, text shapes and notes.
Every other match is listed unticked with the reason it was held back.

A connection a stratum already links is not suggested for that stratum, because
adding a second object from it would replace the first. For the same reason, once
you add a match, other matches from that connection for the same stratum can no
longer be added from the list.

None of these tools writes anything until you add a match, and a dismissed match
is not suggested again. Suggestions read the last saved version of a diagram.

The button under a diagram says how many suggestions there are before you open
it, for example "4 Continuum Link Suggestions Found". It counts every match the
dialog would list, held-back ones included, and it drops as you add or dismiss
them.

## The suggestion index

So that **Suggest Continuum Links** can propose matches without asking your
platforms, Blueprintr keeps its own index of what each connection can see.

### What it stores

The name and subtitle of each object, under the same
audience and detail settings that connection's panels follow, the link to it,
and the reference Blueprintr uses to fetch it again. Identifiers such as
hostnames, addresses, MAC addresses, serial numbers, asset tags and URLs are
stored only as one-way digests, which can be matched but not read back. Alert
state, incidents, metrics, panel content and credentials are not stored.

### Who sees it

Only people who can already use a connection see matches from
its index. The index is never shown as a list of its own; it only produces the
suggestions you review.

### When it updates

Every hour Monday to Friday between 09:00 and 17:00 UTC+2,
and every six hours outside that window. A connection is also queued after you
verify it, resume it, change its settings or its credential, and when an
administrator chooses **Update index**. UTC+2 here is a fixed offset and does
not follow daylight saving.

### Indexed connectors

24 connectors are indexed: PagerDuty, incident.io, Rootly,
FireHydrant, xMatters, Datadog, New Relic, Dynatrace, Elastic, Splunk
Observability, SolarWinds Observability SaaS, Grafana Alerting, LogicMonitor,
Auvik, Azure Monitor, Google Cloud Monitoring, Pingdom, Better Stack,
UptimeRobot, Checkly, Site24x7, ServiceNow CMDB, GitHub and GitLab. Every other
connector, including every connector served by the
[local agent](/foliums/blueprintr-user-guide/continuum/local-agent), is checked
live instead.

### Some object types only

Seven of these connectors index only some of the
objects a live check can return, so matches from their index are always held
back for review and **Check live** asks those connections too:

| Connector | Left to the live check |
| --- | --- |
| Datadog | Monitor names on a Summary connection, and `service:`, `slo:` and partial `host:` name searches |
| GitHub | Public repositories that are not in the token's own repository list |
| GitLab | Projects the token is not a member of, such as public and internal ones |
| incident.io | Incidents, and Catalog types the index skips because they may describe people or on-call schedules |
| New Relic | Entity types outside a fixed list of stable inventory, such as people, secure credentials, issues, incidents, dashboards, work items and containers |
| ServiceNow CMDB | IP-address and network-adapter records |
| xMatters | People and events. The index keeps groups only |

### Limits

An index holds at most 50,000 objects for one connection. A
connection with more is marked incomplete.

### Incomplete indexes

An index is also marked incomplete when the platform
cannot be listed to the end, and when objects were left out because the
reference Blueprintr keeps for them includes a URL with credentials or a secret
parameter such as a token, for example a monitored web address. Such objects are
skipped, never stored with the secret removed. An incomplete index keeps its
matches held back until a later update lists the platform in full.

### Empty listings

If a connection whose index has objects lists nothing,
Blueprintr keeps the previous index and marks it incomplete. Only a second empty
listing in a row replaces it, and that update waits for the normal schedule even
when an administrator chooses **Update index** or verifies the connection sooner.

### Held back

Matches from an index that is incomplete, or more than 12 hours
old, are listed with that reason and never ticked for you, because a closer
match may be missing from it. **Check live** asks those connections directly.

### What it can and cannot find

The index reaches objects beyond the page
limits a live search works within, so it can find matches a live check misses.
A live check searches text the index does not hold, so it can find matches the
index misses. Neither is a subset of the other.

### When an index is deleted

Indexing switched off for that connection, the
connection suspended, its token removed or replaced, its settings saved, a
failed verification, a credential the platform rejects, the connection deleted,
the plan lapsing (within about an hour), and seven days without a successful
update. Database backups keep deleted rows for their retention period.

The index never writes to a blueprint. Adding a match still fetches a live
snapshot through the same path as any other link.

## Refreshing is manual

Opening a tab shows its saved snapshot and contacts nothing. Nothing polls a
platform to update a tab, and no tab is refreshed on a schedule. The one thing
Blueprintr runs on a schedule is the [suggestion index](#the-suggestion-index),
which proposes links and never changes a tab.

Each linked row has two icon buttons with no visible text. The circular-arrows
icon re-fetches, and its tooltip reads "Re-fetch this integration's data". The
broken-link icon removes the tab, with the tooltip "Remove this integration tab",
and asks you to confirm.

A banner above every saved tab states which of these applies:

| Banner | Meaning |
| --- | --- |
| Saved snapshot | The last fetch succeeded and is still considered fresh |
| Snapshot needs a refresh | Older than the connector's freshness window |
| Incomplete snapshot | Retrieval was limited or some sections could not be read; check section coverage before interpreting counts |
| Last refresh failed | The previous snapshot is still shown, unchanged |
| Refresh paused | The connection is suspended |

Ten connectors declare a freshness window: PagerDuty, incident.io, Rootly,
Datadog, LogicMonitor, Auvik, Jira Cloud, Jira Service Management Operations,
ServiceNow and GitHub. Most set five minutes. Jira Cloud work items and GitHub set fifteen, Jira
Service Management on-call coverage sets two, and ServiceNow sets one day.

> [!IMPORTANT]
> The other eighteen connectors never report a snapshot as needing a refresh. A
> months-old Grafana tab still reads "Saved snapshot". Check the
> fetch time on the tab rather than trusting the banner.

The banner is a reminder to refresh, never automatic polling.

The GitHub connector distinguishes an empty result from incomplete or unavailable
reads. A repository metadata/identity failure preserves its previous snapshot;
an enabled section failure is marked in a newly saved partial snapshot. Coverage
and failure handling vary by connector; consult its guide before interpreting absence.

## Who can read a saved panel

This depends on the connector, so check it before linking.

| Connector | Default audience for a new connection |
| --- | --- |
| Datadog, LogicMonitor, Auvik, Rootly, ServiceNow, GitHub, NetBox | Blueprint editors only |
| Infoblox, Veeam Backup & Replication | Blueprint editors only, with no setting to widen it |
| Every other connector | Everyone who can read the stratum |

A connector in the last row has no audience setting, so its panel reaches every
reader of the blueprint. On a public blueprint that includes anonymous readers,
embeds and exports. The seven connectors in the first row offer a reader-visible
option labelled **All Blueprint readers**; on four of them the full label adds
"approved metadata".

> [!IMPORTANT]
> A Datadog or LogicMonitor connection created before those settings existed
> keeps its historical behaviour, which is reader-visible and detailed, until an
> administrator changes it in **Configure**. Its form shows those historical
> values, so saving without changing them keeps them. Check old connections
> rather than assuming the newer defaults apply. Rootly, Auvik, ServiceNow and
> GitHub read a missing audience setting as Blueprint editors only for future
> fetches, and a missing detail setting as summary on Auvik and GitHub and as
> detailed on ServiceNow. See the
> [GitHub guide](/foliums/blueprintr-user-guide/continuum/github).

An audience change applies to later fetches. It does not rewrite snapshots
already saved, and it cannot recall versions, templates, exports, embeds or AI
answers that already carry the data. Unlinking a tab and revoking a credential
cannot recall them either.

## Managing a connection

| Control | What it does |
| --- | --- |
| **Configure** | Edits the connection's non-secret settings, including audience and detail |
| **Verify** | Re-runs the handshake, including optional capabilities |
| **Suspend** / **Resume** | Stops and restarts search and refresh. Saved snapshots stay readable |
| **Rotate token** or **Replace credentials** | Reveals a field, then **Verify & replace** swaps the credential only if the new one verifies |
| **Remove token…** | Clears the stored credential and suspends the connection |
| **Update index** | Asks for a fresh pass of the suggestion index now, unless one ran in the last few minutes |
| **Stop indexing…** / **Start indexing** | Leaves this connection out of the suggestion index, or puts it back. Stopping deletes its index, and its matches are then checked live |

Deleting a connection is refused while tabs are still bound to it: "This
integration has N stratum tab(s) bound to it. Remove those first."

If the plan lapses, the section stays open in a cleanup-only mode. You can
suspend, inspect, unlink and disconnect. Adding or refreshing data needs
Enterprise again, and the suggestion indexes for that owner's connections are
deleted within about an hour.

## Which platforms

39 connectors are registered. 29 work directly, and 10 more need the
[local agent](/foliums/blueprintr-user-guide/continuum/local-agent) for systems
Blueprintr cannot reach.

The [connector reference](/foliums/blueprintr-user-guide/continuum/connector-reference)
lists all of them with what each one asks for and shows. These have a guide of
their own:

> [!TILES 3]
>
> === [PagerDuty](/foliums/blueprintr-user-guide/continuum/pagerduty)
>
> Service ownership, incident state and on-call coverage.
>
> === [incident.io](/foliums/blueprintr-user-guide/continuum/incident-io)
>
> Catalog services and the incidents attached to them.
>
> === [Rootly](/foliums/blueprintr-user-guide/continuum/rootly)
>
> Incident response and follow-up progress.
>
> === [Jira](/foliums/blueprintr-user-guide/continuum/jira)
>
> Work items, and alerting from Service Management Operations.
>
> === [Datadog](/foliums/blueprintr-user-guide/continuum/datadog)
>
> Hosts, monitors, catalog services and reliability objectives.
>
> === [LogicMonitor](/foliums/blueprintr-user-guide/continuum/logicmonitor)
>
> Devices, DataSource instances and resource groups.
>
> === [Auvik](/foliums/blueprintr-user-guide/continuum/auvik)
>
> Network device context and recent alert history.
>
> === [ServiceNow CMDB](/foliums/blueprintr-user-guide/continuum/servicenow)
>
> The configuration item, its relationships and its open work.
>
> === [GitHub](/foliums/blueprintr-user-guide/continuum/github)
>
> Repository context, open work, CI runs and deployment evidence.

---

# Blueprintr User Guide: Connector reference
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/connector-reference

> Every Continuum Link connector, what it asks for when you connect it, and what its saved panel shows.

39 connectors are registered. 29 connect directly and 10 need the
[local agent](/foliums/blueprintr-user-guide/continuum/local-agent). All of them are
[Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link), so all
of them need an Enterprise plan and `continuum_integrations.manage`, and none of
them draws on a canvas.

Every connector can be found by free-text search when linking a stratum. Where a
credential field has no label of its own, the form calls it **API token**.

## Alerting and on-call

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [PagerDuty](/foliums/blueprintr-user-guide/continuum/pagerduty) | API token | PagerDuty region, Imported content | Service identity, open incidents, incident coverage, ownership, on-call coverage, related services |
| [incident.io](/foliums/blueprintr-user-guide/continuum/incident-io) | API key | Catalog types, relationship fields, attributes, history days, remediation counts | Catalog entry and related incidents, or one incident with durations and follow-ups |
| [Rootly](/foliums/blueprintr-user-guide/continuum/rootly) | API key | Content audience, ownership context, on-call coverage, action item counts | Service response and history, or one incident's lifecycle |
| [Jira Service Management Operations](/foliums/blueprintr-user-guide/continuum/jira) | Atlassian sign-in | Site, counts-only | Alert scope with open, unacknowledged and snoozed counts, or an on-call schedule |
| FireHydrant | API key | None | Service tier and active incidents, or one incident |
| Splunk On-Call | API credentials (JSON) | None | One incident, paged teams and state transitions |
| xMatters | Password | Instance URL, Username | A group, a person or an event, with recent events |

## Observability

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [Datadog](/foliums/blueprintr-user-guide/continuum/datadog) | Datadog credentials | Datadog site, content audience, saved detail, approved tag keys, Software Catalog, SLOs, default SLO window | Host, monitor, catalog service or reliability objective |
| New Relic | User API key | Region (optional) | Entity identity, alert severity, reporting state and tags |
| Dynatrace | API token | Environment URL | Entity identity and open problems by category, with a timeline |
| Elastic Observability | API key | Kibana URL | Alert rule identity, active count and execution status |
| Splunk Observability Cloud | Access token | Realm | Detector state, active incidents by severity, current signals |
| SolarWinds Observability SaaS | API token | Data centre | Entity identity, health state, maintenance and telemetry age |
| Grafana Alerting | Service account token | Grafana URL | Firing alerts for a label matcher, or one alert rule's state |

> [!IMPORTANT]
> Every cloud connector reaches its provider from Blueprintr over HTTPS and is
> blocked from private, loopback, link-local, carrier-NAT and metadata addresses.
> Any URL field in these tables must name a publicly reachable host: Grafana,
> Alertmanager, Kibana, Dynatrace environment, self-hosted GitLab, xMatters and
> ServiceNow included. An internal host needs one of the on-premise connectors
> below, and Grafana, Alertmanager, Elastic, Dynatrace and GitLab are not among
> them.

## Monitoring

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [LogicMonitor](/foliums/blueprintr-user-guide/continuum/logicmonitor) | Bearer token | Company, content audience, saved detail, group scope, maintenance context, instance datapoints | Device, DataSource instance or resource group |
| [Auvik](/foliums/blueprintr-user-guide/continuum/auvik) | API key | Region, Username, site scope, audience, saved detail, alert history period, optional sections | Device context and recent alert history |
| AWS CloudWatch | None | A verified AWS cloud connection and a region | An alarm with recent state changes, or a log group with event volume |
| Azure Monitor | Client secret | Tenant ID, Client ID, Subscription ID | Resource identity, alerts by severity, recent alerts |
| Google Cloud Monitoring | Service account key (JSON) | Project ID | Alert policy and its conditions |
| Prometheus Alertmanager | Password | Alertmanager URL, Username (optional) | Alert counts for a matcher, top labels, firing since |

CloudWatch is the one cloud connector that stores no credential of its own. It
reuses a verified
[cloud connection](/foliums/blueprintr-user-guide/continuum/cloud-connections),
so the form offers a connection and region picker instead of a token field.

That connection's role needs nine CloudWatch and Logs actions the discovery role
does not grant. The form lists them under **Required IAM actions for the backing
role**; add them before expecting alarm or log-group data. On an organisation-mode
connection the form also asks for a 12-digit member account id.

Alertmanager always requires a secret to save the connection. For an
unauthenticated instance, leave **Username** blank and type any placeholder in
**Password**. It is never sent without a username.

Google Cloud Monitoring shows alert-policy configuration only. Its panel states
"Open incidents unavailable".

## Uptime and synthetics

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| Pingdom | API token | None | Check identity, uptime percentage, average response, state changes |
| Better Stack Uptime | API token | None | Monitor identity, SLA and incident counts, active incidents |
| UptimeRobot | API key | None | Monitor identity, recent health and window totals |
| Checkly | API key | Account ID | Check identity, sampled results, latest runs |
| Site24x7 | OAuth credentials (JSON) | OAuth client ID, Data centre (optional) | Monitor state, account-wide fleet status, current problem monitors |

## Service management and source control

| Connector | Credential | Other fields | Panel |
| --- | --- | --- | --- |
| [Jira Cloud work items](/foliums/blueprintr-user-guide/continuum/jira) | Atlassian sign-in | Site, counts-only | One work item, a saved filter or a JQL scope |
| [ServiceNow CMDB](/foliums/blueprintr-user-guide/continuum/servicenow) | Password | Instance URL, Username, Snapshot audience, Saved detail, Open work | Configuration item with lifecycle, environment, ownership groups and discovery dates; relationships from the CI's side with the total; optional open incident and change counts |
| [GitHub](/foliums/blueprintr-user-guide/continuum/github) | Fine-grained access token | Verification repository, optional organisation, enabled reads, audience and detail | Repository context scoped by branch/workflow, labels, environment and path; separate work and CI, optional deployment, commit and release evidence |
| GitLab | Access token | Instance URL (optional) | Project identity, activity, recent issues and pipelines |

> [!NOTE]
> GitHub and GitLab take a pasted access token. There is no sign-in button on the
> Continuum connection form; Jira is the only connector that signs you in.

## On-premise, through the local agent

These ten appear in the connector list but cannot be selected until the
organisation has an enrolled agent online that can serve them. Until then the
option is disabled and its label says why: set up an agent, the agent is offline,
or upgrade the agent. Blueprintr never stores their credentials. Set in the
agent's own configuration, a credential never leaves your network; sent from the
Continuum Local panel instead (the agent must allow it), it passes through
Blueprintr to the agent without being saved. The connection form has no
credential field, and shows the account each product needs under its notice.

| Connector | Credential parts in the agent config | Other fields | Panel |
| --- | --- | --- | --- |
| SolarWinds Orion | `username` and `password` | Orion server URL | Node identity, health metrics, active alerts, interfaces, volumes |
| Zabbix | `token` | Zabbix frontend URL | Host identity, unresolved problems, current problems |
| PRTG Network Monitor | `token` | PRTG server URL | Device identity, sensor counts, unhealthy sensors |
| Checkmk | `username` and `password` | Checkmk URL, Site | Host identity, service states, current problems |
| Icinga 2 | `username` and `password` | API URL | Host identity, service states, active problems |
| ManageEngine OpManager | `token` | OpManager URL | Device identity, active alarms |
| WhatsUp Gold | `username` and `password` | WhatsUp Gold URL | Device identity and active monitor counts |
| NetBox | `token` | NetBox URL, Custom fields to show, Snapshot audience | Device or virtual machine identity, primary addresses, interfaces with MACs, addresses and cabled peers, and the listed custom fields |
| Infoblox | `username` and `password` | Grid Manager URL, WAPI version, Extensible attributes to show | A host, an address or a network: DNS records, IPAM state, DHCP leases and fixed addresses, network utilization and the listed extensible attributes |
| Veeam Backup & Replication | `username` and `password` | Backup server URL, REST API version, Restore point target | Protection verdict, age of the last good restore point, jobs protecting the machine and their last result, recent failures |

For SolarWinds Orion, Checkmk, Icinga 2 and Infoblox the username is part of the
agent's credential, so the connection form does not ask for it. It shows what that
account needs instead; set the username with the password, in the agent config or
from the Continuum Local panel.

Each one wants a dedicated account that can only read, on a known port, and most
need a certificate given to the agent. A port in the connector's URL replaces
the default. The
[Continuum Local page](/foliums/blueprintr-user-guide/continuum/local-agent)
explains the certificate column.

| Connector | Least-privilege account | Default port | Certificate |
| --- | --- | --- | --- |
| SolarWinds Orion | No administrator, node management or unmanage rights | 17774 | Self-signed on install |
| Zabbix | Role type User, Read on the host groups to show | 443 | Depends on the install |
| PRTG Network Monitor | API key with Read access, Read-only user | 443 | Self-signed on install |
| Checkmk | Role copied from Guest, plus Read access to all hosts and folders | 443 | Depends on the install |
| Icinga 2 | ApiUser with `objects/query/Host` and `objects/query/Service` only | 5665 | Icinga's own CA |
| ManageEngine OpManager | API key with Read access only | 8060. Write it in the URL: without a port, the connector uses 443 | Self-signed on install |
| WhatsUp Gold | Read-only user that can read the Entire Network group | 9644 | Depends on the install |
| NetBox | View on devices, interfaces, IP addresses, VMs and VM interfaces only; Write enabled off | 443 | Depends on the install |
| Infoblox | Own admin group with API access and read-only permissions, no superuser | 443 | Issued to www.infoblox.com: replace it first |
| Veeam Backup & Replication | Veeam Backup Viewer role only | 9419 | Self-signed on install |

### NetBox

Supports NetBox 4.0 and later; verify refuses an older release,
because before 4.0 NetBox ignores the list of fields Blueprintr asks for and
would send config contexts. Enter the token alone, without the word Token or
Bearer. v1 tokens are 40 characters; v2 tokens (NetBox 4.5 and later) begin
`nbt_` and include the part after the dot. Either works. Blueprintr never asks
for config contexts or comments. It asks for custom fields only when you list
some under Custom fields to show; left blank, or set to `none`, no custom field
value leaves NetBox. NetBox cannot send only some custom fields, so while any
are listed, NetBox sends Blueprintr every custom field value on the device or
virtual machine: panels show only the listed ones, and the rest are deleted with
the request within minutes. A custom field named like a credential is never
shown, even when listed. If you keep secrets in custom fields, leave the list
blank. The panel is for Blueprint editors unless you choose all Blueprint
readers.

### Infoblox

Leave the WAPI version blank on NIOS 8.6 and later (2.12). The
certificate NIOS installs with is issued to www.infoblox.com, so replace it with
one for the Grid Master's address before giving it to the agent as `caFile`; the
Continuum Local page has the steps. While any extensible attributes are shown,
the grid sends Blueprintr all of an object's extensible attributes: panels show
only the listed ones, and the rest are deleted with the request within minutes.
Enter `none` and Blueprintr never asks for them. If you keep secrets in
extensible attributes, use `none`. Panels are for Blueprint editors only, since
leases and MAC addresses can identify people on client networks.

### Veeam Backup & Replication

Needs version 12 or later and agent 0.2.0 or
later, which keeps Veeam's access token on the agent. On 12.0, set the REST API
version to `1.1-rev0`. The build number in the verify message needs the Backup
Administrator role, and is left out for a Backup Viewer. The tab measures a
restore point's age on the backup server's own clock. A job that includes a
machine through a folder, tag or cluster is found through the machine's restore
points, not through the job definition. Panels are for Blueprint editors only.

## Reading any panel

Whatever the connector, the same rules hold.

- Data is fetched with the connection's credential, not the reader's. A source
  link opens the provider, which applies its own permissions.
- A panel is a named projection of the provider's response. The raw upstream
  object is never stored as-is.
- A failed read never becomes a zero. Sections are marked unavailable or partial,
  and partial counts are lower bounds.
- A provider that cannot be reached leaves the saved snapshot in place. The tab
  keeps its last successful body and the banner reads "Last refresh failed". A
  first link that cannot fetch is refused, so no tab is created.
- A saved panel reaches everyone who can read the blueprint unless its connector
  has an audience setting or keeps its panels for editors. Datadog, LogicMonitor,
  Auvik, Rootly, ServiceNow, GitHub and NetBox have the setting, and Infoblox and
  Veeam Backup & Replication panels are always for Blueprint editors only. On a
  public blueprint every other panel is visible to anonymous readers, embeds and
  exports.
- 24 connectors are indexed so **Suggest Continuum Links** can propose matches
  without asking the platform: PagerDuty, incident.io, Rootly, FireHydrant,
  xMatters, Datadog, New Relic, Dynatrace, Elastic, Splunk Observability,
  SolarWinds Observability SaaS, Grafana Alerting, LogicMonitor, Auvik, Azure
  Monitor, Google Cloud Monitoring, Pingdom, Better Stack, UptimeRobot, Checkly,
  Site24x7, ServiceNow CMDB, GitHub and GitLab. The index holds object names,
  links and one-way digests of identifiers, under the same audience and detail
  settings. Datadog, GitHub, GitLab,
  incident.io, New Relic, ServiceNow CMDB and xMatters index only some of their
  object types, so their matches are held back for review and also checked live.
  Every other connector is checked live.
- Counts describe what was retrieved at the stated time. They are not a statement
  that the component is healthy now.

---

# Blueprintr User Guide: PagerDuty
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/pagerduty

> Service ownership, open incident state and on-call coverage beside the component they belong to.

Link a PagerDuty technical service to the stratum for the component it covers.
The saved tab shows who owns the service, what is open against it, and whether
the primary escalation level had cover when it was fetched. Responding to
incidents stays in PagerDuty.

A PagerDuty technical service is the only object that can be linked. Business
services appear inside a service's panel as related rows, and cannot be linked
on their own.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In PagerDuty, create a dedicated read-only REST API key under
   **Integrations → Developer Tools → API Access Keys**. An Events API
   integration key will not work here. If you paste one, Blueprintr sends it and
   PagerDuty rejects it with "PagerDuty services read failed (HTTP 401). Check or
   replace the REST API key."
3. In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, choose **New integration**, and select
   PagerDuty as the **Type**.
4. Give the connection a **Name**, set the two options below, paste the key into
   **API token**, and choose **Connect & verify**. Without a name the form
   refuses with "Give this integration a name."

### Connection options

Both dropdowns open on **Use default**, which stores nothing and behaves as the
first real option.

| Field | Options | Effect |
| --- | --- | --- |
| **PagerDuty region** | Use default, United States (US), Europe (EU) | Chooses the API host. Use EU for accounts whose address ends in `eu.pagerduty.com`. Default is US |
| **Imported content** | Use default, Summary (recommended), Detailed: include titles and description | Detailed adds incident titles and the service description. Default is Summary |

Verification makes two list calls, one for services and one for incidents. Both
may return nothing and still verify, so a successful check proves the key reads
those collections, not that the account has content. On-call coverage and
service dependencies are not exercised at verification time, so they may still
fail when a service is linked.

## Link a service

Open the stratum and choose **Continuum Link**, then search by any of these.
PagerDuty has no prefix syntax.

| What you type | What happens |
| --- | --- |
| A service name | Searches service names, up to about 300 services |
| A service ID (6 to 32 uppercase letters and digits) | Looked up directly. If PagerDuty returns 404, the same text is searched as a name |
| A PagerDuty service URL | The ID is read out of `/service-directory/<ID>` or `/services/<ID>`. The URL itself is never called |

A URL from the other region is refused rather than looked up: "This PagerDuty
service URL belongs to a different region. Choose the matching connection."

## What the panel shows

| Section | Contents |
| --- | --- |
| Service | Service, Service ID, Region, Incident posture, Meaning, Owning team, Escalation policy, and the description in Detailed mode |
| Open incidents | Counts of reported open, high-urgency, low-urgency, unknown urgency and unknown status |
| Incident coverage | Retrieval, time range, content mode, how many incidents are shown, and a consistency row when the two reads disagree |
| Open incident details | Up to 20 incidents, newest first |
| Ownership in PagerDuty | Links to the escalation policy and the owning team |
| On-call coverage | Whether the primary level had cover, when to recheck, and a privacy note |
| Service relationships | Retrieval state, then a table of related services |

The headline restates PagerDuty's service status: "No open incidents reported",
"Acknowledged incidents", "Triggered incidents", "Maintenance · new incidents
suppressed" or "Disabled · new incidents suppressed". The Meaning row spells out
the limit of that reading: "PagerDuty incident and notification state; not a
measurement of component availability."

If the service read and the incident read disagree, the headline is replaced with
"Service and incident state disagree · refresh to recheck" rather than showing a
healthy state.

### Counting and its limits

Open incidents are those PagerDuty reports as triggered or acknowledged, with no
creation-date cutoff. Retrieval stops after five pages of up to 100, so roughly
500 incidents. When that cap is reached, the section title gains "partial
retrieval", every count gains a trailing plus sign, and the Retrieval row reads
"Partial: stopped after 5 pages; counts are lower bounds."

On-call coverage is computed over one hour starting at the fetch, filtered to the
service's escalation policy. If those pages could not all be read, coverage reads
Unknown rather than claiming a gap: "Coverage retrieval is partial; absence does
not establish a coverage gap." A service with no escalation policy makes no
on-call call at all.

Related services are limited to six detail lookups. Business services never carry
a state, showing "Business impact not retrieved", because the connector does not
infer business impact.

## What is never imported

Responder names, user IDs, email addresses and schedule names are excluded in
both content modes. So are incident bodies, assignees, acknowledgers,
conference-bridge numbers, service integration keys and business-service points
of contact. Detailed mode adds exactly two fields: the incident title, truncated
to 250 characters, and the service description, truncated to 1000 characters.

Only `pagerduty.com` HTTPS links reach the panel, with query strings and
fragments stripped.

## Audience

PagerDuty declares no audience setting, so its saved panel is visible to everyone
who can read the stratum. On a public blueprint that includes anonymous readers,
embeds and exports. Service names, team names and relationships are visible even
in Summary mode.

Choose **Detailed** only when incident titles and the service description are
appropriate for that audience. Reducing detail later applies to subsequent
refreshes and does not recall copies already shared.

## Changing the region later

Changing the region is refused while any binding predates the region setting:
"Remove the existing legacy bindings before changing PagerDuty region, then link
services from the new region."

If every binding does carry a region, the change is allowed, and each of those
services then fails on refresh with "This service was linked in a different
PagerDuty region. Unlink it and choose the service again." The new region is
verified with the existing credential before it saves, so a US-only key fails the
switch to EU and the previous setting is kept.

## Refreshing and recovery

Snapshots become due for refresh after five minutes, which is a reminder rather
than automatic polling. A failed service or incident read keeps the previous
snapshot and adds a warning; it never becomes a healthy zero. A failed on-call or
dependency read marks only that section unavailable and still saves the panel.

---

# Blueprintr User Guide: incident.io
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/incident-io

> Catalog service context and the incidents attached to it, beside the component on the diagram.

Link an incident.io Catalog entry to the stratum for a service or component, and
the tab shows the incidents that named it. Link an incident instead, and the tab
explains one response: its lifecycle, severity, measured durations and follow-up
state. Responding and writing up stay in incident.io.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In incident.io, create a dedicated key under **Settings → API keys** with
   **View data** (`viewer`) and **View catalog** (`catalog_viewer`). Leave write
   permissions and **View all incident data** (`global_access`) disabled.
3. In Blueprintr, open **Settings → Continuum**, go to **Operational
   integrations**, choose **New integration**, and select incident.io as the
   **Type**.
4. Paste the key into **API key**, set any of the optional fields below, and
   choose **Connect & verify**.

Verification reads the key's identity, one incident, the Catalog type list, one
Catalog entry, the custom-field list when relationship fields are configured, and
one follow-up when remediation counts are on. All requests are reads against
`api.incident.io`.

### Optional connection settings

Every field can be left blank. The three list fields accept up to 50
comma-separated IDs each. Ask your incident.io administrator for the stable IDs.

| Field | Blank behaviour | What it changes |
| --- | --- | --- |
| **Catalog types to search** | Searches available types within the retrieval budget | Restricts search to the service or component types your diagrams use |
| **Incident relationship fields** | An incident counts if it selects the entry in any custom field | Counts an incident only when it selects the entry in the listed fields, such as Affected services |
| **Catalog details to share** | No attributes are shown at all | Adds selected structured attributes, such as owning team or tier, visible to every blueprint reader |
| **Recent incident history (days)** | 30 | The window for the "created in the last N days" count. Accepts 1 to 90 |
| **Include remediation counts** | Off | Adds aggregate follow-up state. Needs the `actions.view` permission and the matching incident.io entitlement |

Active, triage and paused incidents are checked regardless of age, so the history
window only bounds the recent-history count.

## Link an object

Open the stratum, choose **Continuum Link**, and search. Once an incident.io
connection is in play, an **incident.io objects** selector appears with
**Catalog and incidents**, **Catalog records** and **Incidents**. Search a name,
a stable ID, an INC number or an incident link.

| What you type | What it finds |
| --- | --- |
| A name | Catalog entries, incidents, or both, depending on the selector |
| `INC-1042` or a bare number | That incident directly, including one older than the history window |
| A 26-character ULID or a UUID | That record directly |
| An `app.incident.io` incident link | That incident directly |

Typing `catalog:` or `incident:` in front of a query narrows it the same way the
selector does.

## What is always excluded

Blueprintr applies its own filter before anything reaches a panel, whatever the
key is permitted to read.

- An incident appears only when incident.io marks it organisation-visible and its
  mode is standard or retrospective. Private, test, tutorial and stream incidents
  never appear. Linking one returns "incident.io incident is private,
  unavailable, or a test record and cannot be linked."
- A Catalog type that represents people or customers is dropped, whether by its
  category or by user, person, customer, contact or employee appearing as a word
  in its name. Linking an entry of that type fails, but the reason is not shown. The editor sees
  the generic "incident.io could not be reached", so check the type's category and
  name before suspecting the connection.
- Only three shapes of Catalog attribute can be shared: numeric, boolean, and a
  relationship to a team, service or product-feature type. Free text is excluded.
  An attribute whose name suggests a secret, a token, an email address or a phone
  number is excluded even when its type is numeric, and selecting it fails
  verification.

Approved attribute values are clamped further: at most 10 records per attribute,
numbers must parse as numbers, and a relationship label must be 160 characters or
fewer with no line break and nothing shaped like an email address.

## What a Catalog panel shows

| Section | Contents |
| --- | --- |
| Catalog entry | Name, Type, ID, External ID, Catalog state, Updated |
| Related incidents | Active, Triage, Paused, created in the last N days, Coverage, Relationship |
| Approved Catalog relationships and metadata | The attributes you selected, or nothing when none are configured |
| Related incident details | Up to 10 incidents, open first and then newest first |

The Coverage row states the limit of the reading: "Organization-visible standard
and retrospective incidents only; private records are excluded. A related
incident does not by itself establish component health."

The headline is one of: "Archived Catalog entry", "Related incident coverage
incomplete", a count of related active incidents, a triage and paused count, or
"No related active incidents in available scope".

## What an incident panel shows

Reference, lifecycle, status, severity, whether a lead is assigned, and created
and updated times. The lead row reads Assigned, Unassigned or Unknown, and never
names the person. Below that sit measured durations with their availability, the
incident's timestamps, and links out to the incident, the postmortem and any
linked issue.

With remediation counts on, a **Follow-ups** section adds outstanding, completed,
not-doing and unknown-status totals. Descriptions and assignees are not imported.

## Partial results

Retrieval is bounded. When a page limit or budget is reached, counts are prefixed
"At least", the panel adds a coverage-incomplete section, and the snapshot is
marked partial. A count from a partial read is a lower bound, never a total.

Common messages an editor sees:

- "incident.io needs Catalog read access. Ask the connection owner to enable
  catalog_viewer and Verify in Settings → Continuum."
- "incident.io needs actions.view access for remediation counts. Enable that read
  permission or turn off remediation counts, then Verify."
- "incident.io results are incomplete. Narrow the Catalog types or search scope,
  then retry; open incident.io for the full view."
- "incident.io request limit reached. Wait a minute, then retry."

## Audience and refreshing

incident.io declares no audience setting, so its saved panel reaches everyone who
can read the stratum, including anonymous readers of a public blueprint. Incident
references, names, severities and any approved Catalog attributes are visible to
them. In incident.io, organisation-visible does not mean suitable for the public,
so review a record before linking it.

Snapshots become due for refresh after five minutes, as a reminder rather than
automatic polling. A failed refresh keeps the previous snapshot with a warning.
Changing a setting applies to later fetches and does not rewrite copies already
saved or shared.

---

# Blueprintr User Guide: Rootly
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/rootly

> Incident response, service context and follow-up progress beside the component they explain.

Connect a Rootly service to the stratum for a system component, or link an
incident to the stratum explaining a failure or recovery process. Readers can
understand the response in the diagram's context and open Rootly for the full
incident record. Blueprintr reads information; incident management stays in
Rootly.

## Connect and choose an object

1. You need an Enterprise licence, edit access to the blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In Rootly, open **Organization Settings → API Keys → Generate New API Key**.
   Prefer a dedicated **Global API key** assigned read-only Incident Response
   and, only if needed, On-Call roles. Personal keys inherit their creator's
   access; Team keys inherit Team Admin permissions. See
   [Rootly's API-key guide](https://docs.rootly.com/api-reference/overview).
3. In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, and choose **New integration**. Select
   **Rootly** as the **Type**, give the connection a **Name**, enter the **API
   key**, review the audience and optional settings, then choose **Connect &
   verify**. Verification checks service and
   incident reads. There is no separate enable step.
4. Save the blueprint, open the relevant stratum, and choose **Continuum Link**.
   Search for the service or incident and review its identity before linking.
   **Suggest integrations…** on a shape and **Scan for integrations** across the
   blueprint both propose Rootly matches, and attach nothing until you apply
   them.

Blueprintr uses Rootly's hosted API at `api.rootly.com`. This connection does not
provide an alternative regional or self-hosted endpoint.

## Choose the information and audience

| Setting | Default | What it changes |
| --- | --- | --- |
| Rootly content audience | Blueprint editors | Keeps saved Rootly details visible to blueprint editors. Choose the reader-visible option, **All Blueprint readers**, only after approving the information for everyone who can read the blueprint. Its full label adds "approved metadata". |
| Service ownership and context | On | For linked services, adds related services, teams, environments, repository names and deployment names. Turn it off to omit optional context reads. |
| On-call coverage | Off | For linked services, adds [on-call coverage](https://docs.rootly.com/api-reference/oncalls/list-on-calls) when the key and Rootly account support it. Individual responders and their contact details are omitted. |
| Incident action item counts | On | For linked incidents, adds aggregate task and follow-up progress from [incident action items](https://docs.rootly.com/api-reference/incidentactionitems/list-incident-action-items). Task descriptions and assignees are omitted. |

The baseline key needs read access to **services and incidents**. Context may
also require team and environment reads; follow-up summaries need incident
action-item reads. On-call coverage needs access to Rootly's on-call data and
the relevant product entitlement. These are permissions on the key's assigned
roles, not OAuth scope strings. Disable an optional capability instead of
granting unrelated administrative access.

Rootly incidents marked private, or without a reliable privacy designation,
are excluded from selection and saved incident data under either audience
setting. Rootly's non-private designation does not itself make an incident
appropriate for the public. Review titles, service names and relationships
before switching to the reader-visible audience.

> [!NOTE]
> Under the editor audience, a candidate is offered under a generic title such as
> "Rootly service" or "Rootly incident INC-42" rather than its real name, because
> a candidate title can become a stratum filename and a filename sits outside the
> audience gate. A stratum minted from one of these is named accordingly.

## Read the snapshot

A service panel separates active response from recent history and maintenance.
Normal incidents and sub-incidents are distinguished by kind; test incidents
do not count as production incidents. The active view is independent of the
30-day history window, so an older unresolved incident can still be relevant.
Maintenance has its own state and planned window when available; it does not
become an outage merely because it is in progress. Rootly documents these filters in its
[incident API](https://docs.rootly.com/api-reference/incidents/list-incidents).

An incident panel shows response state, severity, related services and lifecycle
times when available. **Mitigated** means impact has been reduced or halted;
it does not mean response work is complete. Follow-up progress helps distinguish
incident resolution from outstanding improvement work. Open Rootly to read
descriptions, communicate with responders or change the record.

Opening a tab displays saved data. Re-fetch with the circular-arrows icon on
the linked row, whose tooltip reads "Re-fetch this integration's data". Rootly
snapshots indicate that another refresh is needed after five minutes; this is
a freshness warning, not automatic polling. On-call coverage is limited to the
time checked. Incident counts describe retrieved records, not a guarantee that
the system is healthy.

## Missing information and recovery

An unavailable incident list, incomplete pagination or unreadable optional
section is shown as unavailable or partial, rather than as zero incidents or
no outstanding work. If a whole refresh fails, the prior snapshot remains with
a warning. Check the key's role and expiry; for rate limits, wait for the stated
retry interval before refreshing again.

Rotate a credential with **Rotate token**, then **Verify & replace**, which
swaps it only if the new key verifies. **Suspend** stops search and refresh while
leaving saved snapshots readable, and **Resume** restarts it. The broken-link
icon on the linked row removes the binding. The connection can be deleted after
its bindings have been removed.

## Copies and rollout checks

New snapshots restricted to editors use Blueprintr's existing audience controls for
readers, embeds, viewer exports and search/AI indexing. Editor exports and
backups retain the source. Approved reader-visible snapshots follow the
blueprint's audience, including anonymous readers of a public blueprint.

Settings apply to subsequent fetches. Changing the audience does not rename
existing Strata or link labels, or remove authored notes outside the managed
panel. Review those separately before relying on a narrower audience. Templates,
version history, exports and other existing copies are not retroactively
rewritten or recalled by an audience change, key revocation or unlink.

Before operational rollout, verify the connection against your Rootly account:
service membership, a known older active incident, maintenance, private-incident
exclusion, optional permissions and on-call coverage. Local fixture tests do
not establish your account's entitlements or replace this live check.

---

# Blueprintr User Guide: Jira
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/jira

> Jira work items and Jira Service Management Operations alerting, connected through Atlassian sign-in.

Blueprintr connects to Atlassian three separate times, for three separate jobs.

| Connection | What it reads or writes | Gate |
| --- | --- | --- |
| **Jira Cloud work items** | Work items, saved filters and JQL scopes, on a stratum | Enterprise, `continuum_integrations.manage` |
| **Jira Service Management Operations** | Alerts, Operations teams and on-call schedules, on a stratum | Enterprise, `continuum_integrations.manage` |
| Jira follow-up destination | Creates an issue from a stratum | `webhook.manage` on the organisation, no plan gate |

The first two are Continuum Link connectors. The third is a write path and is
covered at the end of this page.

## Connecting

Both read connectors are created only through Atlassian sign-in. On the
**New integration** form, choosing either provider hides the Name field, the
config fields and the secret field, and offers **Connect with Atlassian**
instead. Pasting a token is refused: "Connect this integration through Atlassian
sign-in."

After consent you choose an Atlassian site, name the connection, and decide the
counts-only setting. Only sites that granted every required scope are offered. If
none did, you see "No Jira Cloud site granted the required access. Check the
app's permissions and your Jira membership, then reconnect."

Scopes requested are fixed per connection:

| Connection | Atlassian scopes |
| --- | --- |
| Jira Cloud work items | `offline_access`, `read:jira-work` |
| Jira Service Management Operations | `offline_access`, `read:ops-alert:jira-service-management`, `read:ops-config:jira-service-management` |
| Jira follow-up destination | `offline_access`, `read:jira-work`, `write:jira-work` |

Blueprintr verifies the connection with a read before saving it, and creates no
test issue. A connection's site cannot be edited afterwards: the row offers
**Reconnect with Atlassian** rather than **Configure**, and reconnecting is
pinned to the original site.

> [!NOTE]
> These connections need an Atlassian OAuth app configured on the Blueprintr
> deployment. Where that is missing, connecting fails and tells you to ask your
> Blueprintr administrator.

## Counts-only

A checkbox on the site-selection page reads "Import counts and operational state
only. Omit work item summaries, alert subjects and query details from blueprint
snapshots."

> [!IMPORTANT]
> Counts-only is one way. Once set, the checkbox is disabled and no path turns it
> back off. Reconnecting cannot clear it either.

It removes the free text from both the rendered tab and the stored payload:

| Object | Removed | Kept |
| --- | --- | --- |
| Work item | Key and summary, type, project, parent, components, target versions, related work | Status, status category, priority, resolution, due date, updated time |
| Query or filter | The JQL, the saved-filter name, and the per-item list | Match count, audience, search consistency, status-category counts |
| Alert scope | The query text, the matching line, the Operations team, both alert lists | Open, unacknowledged and snoozed counts, coverage, recent history, per-priority counts |
| On-call schedule | Schedule name and owning team | Counts, timezone, checked-at |

Candidate titles also become neutral, such as "Jira work item" and "JSM alert
scope", which is what a stratum minted by Scan is named.

## Searching Jira Cloud work items

The syntax hint appears on the connection row in settings, not in the stratum
search box: "Link a work item, filter:123, epic:PROJ-123, or jql: followed by a
query."

| What you type | What it does |
| --- | --- |
| `PROJ-123` | Links that work item |
| A `/browse/KEY-123` URL on the connected site | Links that work item |
| `filter:12345` | Binds the saved filter by ID. Its JQL is re-read on every refresh, so editing it in Jira changes the tab |
| `epic:APP-42` | Work under that epic |
| `jql:` followed by a query | That query |
| Anything else | Searched as a quoted phrase against summaries, never as raw JQL |

Queries are capped at 2,000 characters. A link from a different Atlassian site is
refused without making a request: "This Jira link belongs to a different site.
Choose that site's integration."

A query panel reads at most 250 work items. Past that, the count is a lower bound
and the panel says "Showing at most 250 matching work items. Open Jira for the
full result."

A bound work item shows work item, type, project, status, status category,
priority, resolution, due date and last update, plus parent, components, target
versions and related work when present. A missing value reads "Not set or
unavailable" rather than a healthy default. Descriptions, comments, assignee and
reporter are never fetched.

> [!TIP]
> A work item marked Done does not mean the service it refers to is healthy.

## Searching Jira Service Management Operations

The hint on that connection row reads "Search entity or subject text, query: for
an Operations query, team: or schedule:."

| What you type | What it does |
| --- | --- |
| Plain text | Matches entity or message text |
| `query:` followed by an Operations expression | Uses that expression |
| `team:` followed by text | Finds an Operations team |
| `schedule:` followed by text | Finds an on-call schedule |

> [!IMPORTANT]
> Operations query syntax is not JQL. Sending a JQL string returns "JSM
> Operations rejected this query (HTTP 400|422). Check the Ops search syntax;
> Jira JQL is not supported here."

Queries are capped at 1,000 characters.

An alert panel makes two independent reads on each refresh: current open alerts
matching the saved query, up to 500, and a separate newest-15 history page. A
large volume of newer closed alerts therefore cannot hide an older open one.

The headline follows a strict order. Any open P1 or P2 makes it critical. An
unknown priority or an incomplete read makes it "open alerts · status
incomplete". Zero open alerts reads "No open alerts in this query" only when
retrieval was complete, every priority was known and nothing else warned;
otherwise it reads "No open alerts · recent history unavailable". Partial results
never read as an all-clear: the Coverage row says "Partial retrieval; this is not
an all-clear" and counts are prefixed "At least".

An on-call schedule panel reports schedule, owning team, counts of current people
on call, current team and escalation routes, next people on call, timezone and
when it was checked. Individual responder identities and contact details are
never returned or stored. Where routing is by team or escalation only, the status
reads "On-call routing configured; person coverage unconfirmed" rather than
naming anyone as on call.

## Freshness and audience

| Snapshot | Marked due for refresh after |
| --- | --- |
| Jira work item or query | 15 minutes |
| JSM alert scope | 5 minutes |
| JSM on-call schedule | 2 minutes |

Neither connector sets an audience, so both panels reach everyone who can read
the blueprint, including anonymous readers of a public blueprint, embeds and
exports. Counts-only is the control for that exposure, and it applies from the
next refresh onward rather than rewriting saved snapshots.

## Creating a Jira follow-up from a stratum

Configure a Jira destination on the organisation's **Settings → Continuum** page.
Choose **+ New webhook**, set the destination to Jira, then choose **Connect Jira
account** to sign in with Atlassian a second time and grant `write:jira-work`.

> [!IMPORTANT]
> A connection made for Continuum Link holds read access only. It is listed as
> "(read access only)" and cannot be chosen. The write connection is a separate
> sign-in.

Pick the project, work type and required fields, then use **Verify without
creating a work item** before saving. The work type must have Description on its
Jira creation screen, or the destination is refused. Every required field on that
screen without a Jira default must also be given a value here.

The **Jira follow-up** button then appears in the stratum tab strip for an author
who can edit the blueprint and holds `webhook.manage` on the owning organisation.
A blueprint with no owning organisation never shows it.

The dialog is titled **Create Jira follow-up** and asks for a destination, a
summary of up to 240 characters prefilled as "Follow up: <stratum name>", and
what needs to happen, up to 12,000 characters. **Create Jira issue** submits it.
Your own submission is the approval step; nobody else reviews it. The text is
recorded durably before Jira is contacted, so a retry cannot create a second
issue, and reusing a request with different text is refused.

The created issue links back to the stratum. Its key can then be linked through
the Jira Cloud connector to follow progress.

New destinations create follow-ups manually only. Automatic creation is opt-in
and limited to four events: a blueprint being published, and a workflow run being
submitted, approved or rejected.

> [!NOTE]
> The write connection has no plan gate. An organisation holding `webhook.manage`
> can create follow-ups without Enterprise, even though it cannot use Continuum
> Link to read Jira back.

---

# Blueprintr User Guide: Datadog
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/datadog

> Monitor conditions, service ownership and selected reliability objectives beside the component they explain.

Connect Datadog to the Stratum for a component on your diagram. Use a host to
explain telemetry reporting, a monitor to explain an evaluated condition, a
catalog service to explain ownership and dependencies, or an SLO to show
performance against an objective. Open the linked Datadog record for detailed
investigation and operational changes.

## Connect

1. You need Enterprise, edit access to the Blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. Create a dedicated Datadog service account with read permissions. Under **Datadog credentials**, set **Credential type** to **API key and
   application key**, or to **Service Access Token** and fill that field. A
   Service Access Token pasted into the application-key box is rejected.
   Follow Datadog's [key setup](https://docs.datadoghq.com/account_management/api-app-keys/)
   or [Service Access Token guide](https://docs.datadoghq.com/account_management/service-access-tokens/).
3. In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, choose **New integration**, select
   **Datadog** as the **Type**, enter a **Name**, and choose the **Datadog
   site**. If you use a custom Datadog domain, find the
   underlying site in **My Preferences**. See [Datadog sites](https://docs.datadoghq.com/getting_started/site/).
4. Review the information and audience settings, enter credentials in the
   labelled password fields, and choose **Connect & verify**. Blueprintr stores
   credentials encrypted and never displays them after saving.

Hosts and monitors require `hosts_read` and `monitors_read`. Enable optional
capabilities only when needed:

| Capability | Additional permission | Information saved |
| --- | --- | --- |
| Service Definitions, schema v2.2 and earlier | `apm_service_catalog_read` | Service ownership and structured operating links |
| Software Catalog, schema v3 | `apm_service_catalog_read` | Supported catalog entities, owners and declared or discovered relationships |
| Reliability objectives | `slos_read` | Selected SLO target, performance, observation window and error budget |

Catalog versions use distinct APIs. Choose the one your account uses and
verify availability on your site. Datadog sites are independent and product
availability differs. The connection reads existing information; it does not
create monitors, SLOs, public dashboards or new telemetry instrumentation.
Your existing Datadog entitlements and API limits still apply.

## Choose the component's operational context

Save the Blueprint, open its Stratum, and choose **Continuum Link**. Search by
host or monitor name, paste a Datadog monitor, SLO or infrastructure source
link, or use one of these forms:

| Search | Use |
| --- | --- |
| `monitor:12345` | Select an exact monitor |
| `service:checkout env:production` | Find the catalog service for this deployment |
| `slo:0123456789abcdef0123456789abcdef` | Select an exact SLO |
| `slo-id:objective-id` | Explicitly select an SLO by its exact ID, including other supported ID formats |
| `slo:Checkout availability` | Find a named objective |

Review the connection, stable identity and source preview before linking.
Catalog and SLO searches require the corresponding connection option.
Linking a Datadog **service** requires its exact `env` tag value, without spaces
or wildcards. For other Catalog entity kinds the field reads **Environment
(optional)** and may be left blank. The service identity
and deployment environment serve different purposes; changing a deployment's
`version` tag does not make it a new service.
[Unified service tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/)
explains Datadog's `service`, `env` and `version` relationships.

Add an explicitly selected SLO ID to a service and choose its window.
Check that the objective describes this service and environment: a similar
name is not proof of that relationship. Standalone SLO selection also lets you
choose 7, 30 or 90 days, where supported by the objective.

For a multi-alert monitor, optionally copy the exact Datadog group string to
show that group's state. Without a group, the panel describes the monitor's
aggregate state. One monitor may cover many hosts or environments; its
aggregate alert is not proof that every component is affected.

Scan and Suggest offer matches for review. Use manual search when you want to
choose an environment, SLO or monitor group. Each connection has one managed
tab per Stratum; choosing a different object explicitly replaces its binding.
Authored prose and diagram content stay intact.

## Read the saved information

Host reporting means whether Datadog received the expected metrics. Missing
telemetry is not proof that a host is down. Hosts outside Datadog's available
inventory window can become unavailable. Monitor panels retain distinct
alert, warning, no-data and other provider states; these are evaluated
conditions, not a general guarantee of system health.

Catalog v3 separates declared relationships from those Datadog discovers
through APM or Universal Service Monitoring. If provenance cannot be established,
it is labelled unknown. These relationships are catalog-wide; the selected
monitor environment does not filter this topology. The earlier Service
Definitions API supplies ownership and links, with no relationship retrieval.
Catalog navigation opens your regional Software Catalog; use the displayed
entity identity to locate the component. Structured operating links may include documentation, runbooks
and dashboards recorded on the selected entity. Blueprintr does not discover
every dashboard or publish dashboard contents.

SLO panels show the objective's target and calculated performance for the
selected window. Error budgets retain their units and may be negative when
the budget is exhausted. Blueprintr never substitutes 100% for an unavailable
calculation. Datadog's own no-data rules still apply: monitor SLOs follow the
underlying monitors' settings, and time-slice SLOs count no-data periods as
uptime. The panel explains these limits. See Datadog's [SLO history](https://docs.datadoghq.com/api/latest/service-level-objectives/get-an-slos-history/)
and [monitor details](https://docs.datadoghq.com/api/latest/monitors/get-a-monitors-details/).

Opening a tab displays its saved snapshot. Re-fetch with the circular-arrows icon
on the linked row ("Re-fetch this integration's data").
Snapshots show their retrieval time and become due for refresh after five
minutes; this is a freshness warning, not automatic polling. Incomplete
retrieval is labelled partial. Counts from a partial list are lower bounds;
an unavailable section does not mean zero. A failed refresh keeps the previous
snapshot with a warning.

## Information and audience

New connections default to **Blueprint editors** and **Summary**. Summary
retains the identity and operational measures while keeping monitor detail to a minimum.
Detailed mode can include monitor names and approved tag values; new
connections approve only `service`, `env` and `version` tag keys initially.
Enter `none` to omit tags; clearing a configured list also omits tags on the
next refresh. Monitor messages, notification recipients and raw telemetry are omitted.

Choose the reader-visible option, **All Blueprint readers**, whose full label
adds "approved metadata", only after reviewing the
information for that audience. A public Blueprint can have anonymous readers
who do not authenticate to Datadog. Host identities, service names, ownership,
links and even selected tag values may be confidential.

A connection created before these settings existed has no stored value for
audience, saved detail or approved tag keys. Each absent value resolves to its
legacy behaviour: blueprint readers, detailed, and every tag key up to 30,
excluding keys whose name suggests a secret. Such a connection publishes monitor
names and all tag values to everyone who can read the blueprint.

Opening **Configure** and saving unchanged keeps that behaviour, because the form
pre-selects the legacy values. Select **Blueprint editors** under **Datadog
content audience**, choose **Summary** under **Saved detail**, set **Approved tag
keys** or enter `none`, choose **Verify & save settings**, then refresh each
linked tab. Settings affect subsequent successful refreshes;
they do not rewrite existing snapshots. Editor-only panels follow the shared
reader, embed, viewer-export and search/AI audience controls. Editor exports
and backups can retain the source data. Names in authored notes or link labels
outside the managed panel need separate review.

Unlinking, reducing detail, revoking credentials or changing audience does not
recall saved versions, templates, exports, AI answers or copies already shared.

## Recovery and disconnection

Verification checks the required reads and enabled optional capabilities.
Host and monitor reads must pass. If an enabled Catalog or SLO check fails,
the connection stays usable for hosts and monitors and the verification notice
shows which optional access needs attention. After reloading settings, use
**Verify** to recheck optional availability; the stored verified status alone
does not establish it.
If access is denied, check the site's selection, credential expiry and exact
read permissions. Scoped keys do not inherit extra permissions. Newly created
keys can take a few seconds to propagate. For rate limits, wait for the stated
retry interval before refreshing; see [Datadog's rate-limit guidance](https://docs.datadoghq.com/api/latest/rate-limits/).

Use **Verify & replace** for credentials. Replacing an application key while
keeping the same API key preserves links. Changing the API key or Service
Access Token requires reviewing and linking objects again, because Blueprintr
cannot assume the new credential addresses the same account. Changing sites
also requires relinking. Older bindings must be unlinked before these changes.
A failed credential verification preserves the previous credential.

**Suspend** stops search and refresh while retaining snapshots, and **Resume**
restarts it. The broken-link icon on the linked row removes the binding and its
managed tab. Remove all bindings before deleting
a connection. Remove its stored credential and revoke it in Datadog when access
should end.

Before operational rollout, validate your site's permissions, known host and
monitor groups, missing telemetry, large result sets, SLO calculations, optional
Catalog availability and regional source links against your own account. Local
fixtures do not establish live product availability or account entitlements.

---

# Blueprintr User Guide: LogicMonitor
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/logicmonitor

> Resource, instance and group monitoring context beside the component your diagram explains.

Link a LogicMonitor device, DataSource instance or resource group to the Stratum
for the component it describes. A server can show the conditions affecting it;
a circuit can show the exact monitored interface; a site can show the observed
state of its group members. Keep your explanation alongside the saved
observation. Investigation, alert acknowledgement and configuration changes
remain in LogicMonitor.

## Connect your portal

1. You need an Enterprise licence, blueprint edit access and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In LogicMonitor, create a dedicated
   [API-only user](https://www.logicmonitor.com/support/adding-an-api-only-user).
   Assign a role with **Resources View** on only the resource groups Blueprintr
   should read. Device, group, alert, instance, metric and scheduled downtime
   reads use resource permissions. Write, alert acknowledgement and Collector
   settings permissions are unnecessary. See
   [Resources role permissions](https://www.logicmonitor.com/support/resources-role-permissions).
3. Create a **Bearer** [API token](https://www.logicmonitor.com/support/api-tokens-2)
   for that user. This connector accepts Bearer tokens. LogicMonitor also
   supports LMv1 authentication, but an LMv1 access ID/key pair cannot be pasted
   into this connector's Bearer field.
4. In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, choose **New integration**, select
   **LogicMonitor** as the **Type**, and enter a name, company and Bearer token.
   For `https://acme.logicmonitor.com`, enter `acme` as the company.
5. Review the content audience, saved detail and optional settings below,
   then select **Connect & verify**. Verification checks resource and alert
   reads with the supplied credential. A successful check with no visible
   devices is explained separately: review the user's resource-group access or
   add monitored resources. Verification does not establish complete coverage
   or verify every optional read. Save the blueprint before adding a link.

This connection uses REST v3 on commercial `logicmonitor.com` portals.
The portal host is always built as `<company>.logicmonitor.com`, so LMforGov
portals and custom API hosts cannot be reached. No local
agent is required. Credentials are encrypted and are not displayed again
after saving. LogicMonitor documents the supported authentication methods in
its [REST authentication guide](https://www.logicmonitor.com/support/rest-api-authentication).

## Choose the object your diagram describes

Open the Stratum for your server, interface or site and choose **Continuum Link**
from its **+ Add tab** menu. Only a rich stratum can host a linked tab.
Search its name, hostname or IP, or paste a current UIv4 device or group resource
URL from the portal.
Review the connection, company, object type, stable ID and instance lineage
before choosing **Link object**, especially when names repeat. A successful
first fetch is required before the binding is saved. One connection can have
one linked object on a Stratum; selecting another explicitly replaces that
connection's previous link.

| What the Stratum describes | How to select it | What to check |
| --- | --- | --- |
| A server or network device | Search a name, hostname or IP, or use `device:42` for an exact device ID. | Confirm the company and device identity; the same display name can exist more than once. |
| An interface or monitored component | Find its device, choose **Browse instances**, then select the instance. `instances:42` also lists instances on device 42. | Confirm the device, device-specific DataSource and instance. A DataSource's global ID is different from its device-specific DataSource ID. |
| An exact known instance | Use `instance:42:123:456`: device ID 42, device DataSource ID 123, instance ID 456. | Retain all three IDs; an instance name or portal instance URL alone does not establish its complete identity. |
| A site or service group | Search a group name or use `group:London` or `group:7`. | Confirm the group path and displayed direct/descendant scope. Membership describes an administrative monitoring group, not an architectural dependency. |
| A device within a group | Choose **Browse members** or use `members:7`. | This lists direct members. Browsing changes the search; it does not save a link. |

Scan and Suggest can help match diagram identifiers. Every suggestion still
needs your review. Search results are limited to what the dedicated LogicMonitor
user can read; no match does not prove that the object does not exist. Resolve
any reported search or coverage warning before relying on absence.

## Choose detail, scope and audience

These settings belong to the connection. Detail, audience, maintenance and
datapoint changes apply to subsequent fetches. The group scope is saved with
the selected object: review and relink a group to change its scope.

| Setting | New connection default | What it changes |
| --- | --- | --- |
| LogicMonitor content audience | Blueprint editors | Restricts the saved provider panel to blueprint editors. Choose the reader-visible option, **All Blueprint readers**, whose full label adds "approved metadata", only after approving the content for everyone who can read the blueprint. |
| Saved detail | Summary | Keeps object identity, operational states, counts and coverage with less monitoring detail. **Detailed** adds the affected monitoring names and member context. |
| Resource group scope | Direct members | **Include descendant groups** also includes resources within child groups when selecting a group. Duplicate memberships do not represent separate resources. |
| Maintenance context | Include maintenance windows | Adds available scheduled downtime context. Disable it to skip optional maintenance window reads. Alert downtime flags can still appear in Detailed snapshots. |
| Instance datapoints | Blank | Optionally enter up to three exact comma-separated datapoint names copied from the chosen DataSource instance. Metrics are fetched only for instance links and only when this field is populated. |

Existing connections keep their historical reader-visible detailed behaviour
until an administrator chooses otherwise. Existing settings with no maintenance
option do not enable additional maintenance reads.

Alert messages, acknowledgement comments, arbitrary resource properties and
Collector configuration are not imported. Summary information still includes
resource identity and operational metadata: it is not anonymous. Datapoint names
and availability vary by DataSource; choose names meaningful to the interface
or component rather than assuming every instance provides the same metrics.
The [instance API](https://www.logicmonitor.com/support/getting-datasource-instance-details)
and [data API](https://www.logicmonitor.com/support/getting-data) describe this
resource hierarchy.

## Read the saved observation

The panel distinguishes active alert severity, collection availability and
maintenance. Detailed snapshots also show acknowledgement and the affected
DataSource, instance and datapoint. Acknowledgement means someone has acknowledged an alert; it does
not mean the condition has recovered. Scheduled downtime can suppress
notifications while monitoring continues. A Collector problem means the
resource's current observations may be unavailable. None of these states
should be read as a general guarantee of system health. See
[LogicMonitor's scheduled downtime rules](https://www.logicmonitor.com/support/sdt-tab).

Alerting flags describe the object's local setting. The panel does not resolve
every inherited group or DataSource alert-suppression rule; check the provider
when deciding whether notifications should be sent.

Maintenance windows on an instance panel describe its parent device and can
include other monitoring scopes; they are not all specific to the selected
instance. A group panel reads schedules for the selected group, without
individually retrieving schedules for every member device or child instance.
Use each alert's downtime flag and the portal for precise maintenance scope.

Counts describe the active alerts and resources retrieved within the
connection's permissions and selected scope. If pagination cannot be completed,
the panel marks its coverage as partial; do not treat a lower bound as the full
total. Unknown, missing or unreadable information is not zero. Last NetFlow
receipt, if displayed, describes NetFlow specifically and does not establish
the freshness of all monitored data.

Optional instance metrics request the past hour and show the latest 12 samples
per selected datapoint, together with the requested/returned windows, sample
interval and missing-data information. Summary mode uses generic metric labels;
Detailed mode includes the selected datapoint names. Metric samples are never labelled with a unit. The value column is headed "Value
(unit unspecified)" and the Units row reads "Unit not supplied by LogicMonitor;
untransformed provider values". Blueprintr shows the raw numbers without
inferring a unit, converting the value or deriving a rate. Consult the DataSource definition in LogicMonitor
to interpret the sample correctly.

Opening the Stratum displays a saved snapshot and does not call LogicMonitor.
Re-fetch with the circular-arrows icon on the linked row ("Re-fetch this
integration's data"). After five minutes, the snapshot indicates
that another refresh is needed. This is a freshness reminder, not automatic
polling. Each metric has its own sample time; fetching a panel now does not
make an older provider sample current.

Use the source link to continue investigating the selected device, group or
instance in LogicMonitor. A link does not grant access: the provider still
applies the signed-in user's own permissions. Extended graphs, alert messages,
acknowledgement and configuration remain in the portal.

## Recover from failures and disconnect

A failed required read does not become an empty, healthy observation. A failed
refresh keeps the previous snapshot and shows a warning. An optional section
that cannot be retrieved is marked unavailable or partial. Check resource
permissions and token expiry, then verify the connection again. For rate
limits, wait before retrying; repeated browsing and refreshes consume the
portal's API capacity.

Use **Verify & replace** to rotate a token. The replacement is verified before
it replaces the working credential. **Suspend** stops search and refresh while saved
snapshots stay readable; **Resume** restarts it. The broken-link
icon on the linked row removes the current
binding; delete the connection after its bindings have been removed. Moving to
a different portal requires reviewing and relinking object identities; device
IDs are not portable between companies.

## Sharing and retained copies

Provider data is fetched with the connection's credential. Readers are governed
by the configured Blueprintr audience, not their individual LogicMonitor
permissions. Approved reader-visible content can reach anonymous readers of a
public blueprint, embeds, exports and configured search or AI features.
Editor-only panels use Blueprintr's existing audience controls for those reader
surfaces; editor exports and backups retain the source.

Changing a setting affects later successful fetches. Restricting the audience
does not rewrite panels already saved: refresh each linked tab successfully, or
unlink it, before treating existing LogicMonitor content as editor-only. It does
not redact independent versions, templates, exports or copies already shared. Unlinking,
suspending or revoking a token cannot recall those copies. Authored Stratum names,
link labels and notes remain your content and need a separate audience review.

## Validate before operational rollout

Automated tests exercise simulated provider responses; they do not establish
that a particular LogicMonitor tenant grants the expected access. Before
relying on this integration operationally, verify a least-privilege token,
duplicate names, an exact instance, direct and descendant group membership,
multi-page results, special-character searches and a permission-denied read in
a representative portal. Confirm metric units and gaps, scheduled downtime,
source links, freshness reminders and the published-reader audience. Check
rate limits and any feature entitlements with that tenant. The integration does
not import LogicMonitor topology or create monitoring configuration.

---

# Blueprintr User Guide: Auvik
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/auvik

> Network device context and alert history beside the component they explain.

Link an Auvik Network Management device to the stratum for a switch, firewall,
server or other component in your diagram. The saved panel helps readers identify
the device, understand its network context and review recent alert events. Open
Auvik for its current dashboards, detailed investigation and operational actions.
Continuum Link does not redraw the diagram.

This connection uses **Auvik Network Management**. It does not import Auvik SaaS
Management applications, users, licences or security logs.

## Connect and select sites

1. You need an Enterprise licence, edit access to the blueprint and
   `continuum_integrations.manage` on the connection's organisation or team.
2. Create a dedicated Auvik service account with a custom API-only role and access
   to the intended sites. Give it read access to **API – Device info**,
   **API – Alerts** and **API – Tenants**. Auvik's built-in **Read Only** role does
   not grant these API permissions, and its built-in **API Access Only** role
   grants unrelated reads and tenant editing. Build a custom role with only the
   reads listed above. See
   [Auvik's service-account guidance](https://support.auvik.com/hc/en-us/articles/48529381648660-API-Access-Only-Role-and-Service-Account-Configuration-in-Auvik).
3. In Auvik, open **My Profile → Manage API Credentials** and generate the key.
   In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, choose **New integration**, and select
   **Auvik** as the **Type**. Give the connection a **Name**, then enter
   **Region**, **Username** and the API key.
4. Review **Auvik snapshot audience**, **Saved detail** and the optional sections,
   then choose **Connect & verify**. To restrict the connection to named sites,
   select **Configure** on its row afterwards and open **Auvik site scope**. Clear
   **Include every accessible site**, choose **Load Auvik sites**, tick the sites,
   then choose **Verify & save settings**. Ticking a site does not save it on its
   own. **Exact site IDs** accepts up to 25 comma-separated leaf-site IDs
   instead. Changing the region or username requires saving and verifying again
   before the site list will load.
5. Save the blueprint and open the relevant stratum's **Continuum Link** controls.
   Search by device name, IP address, serial number or stable Auvik API ID and
   review the site, identity and matching evidence before linking.
   **Suggest integrations…** on a shape and **Scan for integrations** across the
   blueprint both offer candidates; selecting one is still an editor decision.

> [!IMPORTANT]
> **Region** is the cluster label in your Auvik **API** hostname,
> `auvikapi.<region>.my.auvik.com`, for example `us1` or `eu1`. It is not your
> customer domain and it is not a URL. Entering a URL is refused with "Enter the
> Auvik cluster region, such as us1; do not enter a URL."

**Include every accessible site** includes current and future sites accessible
to the Auvik service account. Clear it and select exact sites to keep a connection
focused on one customer or environment. The list uses Auvik's site labels or
domain prefixes alongside stable IDs.
Selecting a parent organisation is not a substitute for selecting its leaf sites.
Device names and private IP addresses can repeat across sites: check the site and
stable device ID before attaching a panel.

Verification checks inventory and alert access for each explicitly selected
site. Optional capabilities are checked on one representative site; the result
names that site. The first fetch and later refreshes check the actual linked
device and available data, so a verified connection can still have unavailable
optional observations on another device or site.

## Choose the saved information

| Setting | Default | What it changes |
| --- | --- | --- |
| Auvik snapshot audience | Blueprint editors | Keeps the imported panel visible to blueprint editors. Choose **All Blueprint readers** only after approving the information for everyone who can read the blueprint. Unlike Datadog, LogicMonitor and Rootly, Auvik's reader option carries no "approved metadata" suffix. |
| Saved detail | Summary | Keeps device/site identity, monitoring state, hardware, firmware and event counts. Detailed mode also permits internal IP addresses, serial numbers, network identities and alert names; review the resulting preview before sharing it. |
| Interfaces and connected peers | Off | Adds counts of disabled/impaired interfaces and history for up to two selected enabled interfaces with known peers. Detailed mode also shows up to 12 important interfaces with available peer/network relationships. Requires read access to **API – Interface info**. |
| Maintenance context | Off | Adds available running-configuration backup metadata and lifecycle context. Requires the corresponding device-detail and hardware-lifecycle reads. Configuration bodies are not imported. |
| Performance summary | Off | Adds device availability/outage and interface utilization/discard observations over the previous 24 complete UTC hours. The Auvik account must expose the statistics and the service account must be permitted to read them. |
| Alert history period | 7 days | Chooses a 1-, 7- or 30-day history window. This does not define which alerts are currently active. |

Optional sections can be unavailable because of account permissions, discovery
coverage or product availability. They do not require write access. Ask the Auvik
administrator to grant the specific read permission or leave the section off;
granting an administrative role is unnecessary.

## Read the panel in context

The device status is Auvik's observation at the fetch time. An online device can
still have a fault, and a device marked unmanaged is not evidence of monitoring
coverage. Missing information means unknown or unavailable, not healthy.

Alert history contains events that Auvik recorded during the selected window.
Created, resolved, paused and unpaused events retain their meanings. A created
event is not presented as proof that its alert is still active. Dismissal and
dispatch are separate properties. Use the event's source link to check the
current record in Auvik when using Detailed mode; Summary retains event counts
and the device's dashboard link. The detailed timeline shows the most recent 20
retrieved events, and the scope states which interfaces were included. Detailed
mode also caps the network membership table at 20 networks and the address list
at 12, each with a coverage row stating what was omitted.

Interfaces distinguish whether a port is administratively enabled from its
observed operational state. An administratively disabled port is different from a
failed uplink. Peer and network relationships describe Auvik's discovered
inventory; they do not establish that a route is reachable or that redundancy
will work.

Maintenance information helps prepare a replacement or change. A backup timestamp
does not prove that a restore will succeed. Lifecycle information can include
Auvik's information provider, confidence and source links; review those sources
before treating a predicted end-of-support date as a vendor commitment.

Performance observations cover the previous 24 complete UTC hours with hourly
samples. The panel states its period and units; missing hours remain gaps, and
an hourly average is not an instantaneous measurement or a service availability
guarantee.

## Refresh and recover

Opening the tab shows its saved snapshot. Re-fetch with the circular-arrows icon
on the linked row ("Re-fetch this integration's data"). After
five minutes the snapshot is due for refresh; this is a reminder, not automatic
polling. A failed refresh retains the previous snapshot with a warning. An
unreadable or incomplete optional section is labelled rather than turned into
zero alerts or a successful check.

If access fails, check the account's API role, selected sites and region. An
Auvik account move can require a new region. Unlink every linked Auvik device
before changing it: "Unlink existing Auvik devices before changing region, then
review and link their identities in the new region." For a rate limit, wait before
refreshing again. Choose **Rotate token** on the connection's row, then **Verify & replace**, which
verifies a replacement credential before it swaps. A replacement is refused when
more than 50 linked Auvik identities need checking;
**Suspend** stops search and refresh while leaving snapshots readable, and the
broken-link icon removes the current binding. Delete a
connection after removing its bindings.

Site or credential changes must preserve access to existing links. If a new scope
excludes a linked site, keep it selected or unlink that device first. Older links
without a saved site identity need to be reviewed and linked again before their
scope or credential identity can change.

## Sharing and retained copies

The panel is fetched with the service account's access. Readers do not need their
own Auvik account to see an approved reader-visible snapshot. Opening a source
link still requires their own Auvik access.

Editor-only panels use Blueprintr's existing audience controls for readers,
embeds, viewer exports and search/AI indexing. Approved reader-visible content
follows the blueprint's audience, including the public on a public blueprint.
Editor exports and backups can retain the source information.

Settings apply to later fetches. They do not retract previous exports, version
history, templates or other independent copies, or redact authored titles and
notes outside the managed panel. Review those separately before publishing.
Revoking a key, suspending a connection or unlinking does not recall existing
copies.

Before operational use, compare a known device and its history with your own
Auvik account, confirm the selected sites and optional permissions, and check
the reader view. Some Auvik API capabilities are documented as beta. Local tests
do not establish your account's access or live data completeness.

---

# Blueprintr User Guide: ServiceNow CMDB
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/servicenow

> The configuration item behind a shape, its relationships and its open work, beside the stratum that explains it.

Link a ServiceNow configuration item (CI) to the stratum for the component it
records. The saved tab shows what the CMDB believes about that component: its
class, lifecycle, environment, the groups that own and support it, when
Discovery last saw it, how it relates to other CIs and, if you choose, the open
incidents and changes recorded against it. Changing the record stays in
ServiceNow.

Any record in `cmdb_ci` or a class that extends it can be linked: servers,
network gear, application services, business applications. IP-address and
network-adapter records are found too, but rank below the device with the same
name.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In ServiceNow, create a dedicated integration user. Give it the `cmdb_read`
   role, which reads every CMDB table. If the instance enables the REST API
   ACL, add `snc_platform_rest_api_access` as well. Tick **Web service access
   only** on the user, and keep it out of any policy that demands interactive
   multi-factor authentication: the connection signs in with the password on
   every call and cannot answer a prompt.
3. In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, choose **New integration**, and select
   ServiceNow CMDB as the **Type**.
4. Enter the **Instance URL** (`https://acme.service-now.com`, reachable from
   the public internet), the **Username**, and the password, set the options
   below, and choose **Connect & verify**.

### Connection options

Each dropdown opens on **Use default**, which stores the first option.

| Field | Options | Effect |
| --- | --- | --- |
| **Snapshot audience** | Blueprint editors (recommended), All Blueprint readers | Who can read the saved tab. Readers includes anonymous readers, embeds and exports on a public blueprint |
| **Saved detail** | Detailed (default), Summary | Summary withholds the IP address, FQDN, MAC address, serial number, asset tag, location and description from the tab and from its saved data |
| **Open work** | Not imported (default), Open incidents and changes | Adds open incident and change counts for the CI, with the five newest task numbers and links to the filtered lists |

Verification reads one record from each table the connection will use:
`cmdb_ci`, `cmdb_rel_ci`, and with open work switched on, `incident` and
`change_request`. A table the user cannot read fails verification with its name
and the role that grants it, for example "The ServiceNow account cannot read
cmdb_rel_ci (HTTP 403 Forbidden). Grant cmdb_read, plus
snc_platform_rest_api_access when the REST API ACL is enabled."

Open work needs `sn_incident_read` and `sn_change_read` from the ITSM Roles
plugin, or `itil`. Those roles may count as a fulfiller licence on your
instance; check with your account team before granting them.

On a domain-separated instance the user sees only its own domain, and so does
the tab.

## Link a configuration item

Open the stratum and choose **Continuum Link**, then search by any of these.

| What you type | What happens |
| --- | --- |
| A name, FQDN, serial number or asset tag | Substring match on those four columns, up to 20 results |
| An IP address | Exact match on the CI's IP address column, plus a name match |
| A MAC address, with colons or hyphens | Exact match on the MAC address column in either form |
| A 32-character sys_id | The record itself |

Each result shows its class, IP address, location and lifecycle, so two records
with the same name can be told apart, and its sys_id in the preview.

**Scan** and **Suggest** resolve hostnames, FQDNs, IP addresses, serial numbers
and MAC addresses from the diagram. Identifiers of one kind are folded into a
single query of up to 50, so a full site drawing costs a handful of reads.

## What the panel shows

| Section | Contents |
| --- | --- |
| Configuration item | Name, class, environment, classification, lifecycle stage, install status, operational status, model, manufacturer, and in Detailed mode the location, FQDN, IP address, MAC address, serial number, asset tag and description, then the record's last update in UTC |
| Ownership | Support group, managed-by group and change group. People are never imported |
| Discovery and attestation | When Discovery last and first saw the record and from which source, or "Never", and the attestation status and date |
| Open work | With open work switched on: open incident and change counts, then the five newest of each with priority, state and a link |
| Relationships | Up to 25 relationships as seen from this CI ("Depends on", "Used by", "Located in"), with the other CI's name and class, and the total when there are more |
| In ServiceNow | Links to the record's own form, the Dependency Views map and, with open work on, the filtered incident and change lists |

The headline reads the install status and operational status together, for
example "Installed · Operational". ServiceNow keeps the two fields
independently, so a record retired through install status is shown with a
warning even while its operational status still says Operational. On order, in
stock, in maintenance, repair, standby and ready states are shown as
informational. The CSDM lifecycle stage appears as its own row.

Environment is the record's own environment field. Older records that only set
the legacy "Used for" field show that value instead.

Dates come from the stored value and are labelled UTC. If an instance returns
only display values, the date is shown as ServiceNow formatted it, without a
zone label.

### Counting and its limits

Relationships stop at 25; the section title then reads "Relationships (25 of
61)". Open incidents and changes are read up to 25 each; the count states how
many were retrieved when the total is higher.

## What is never imported

Person fields (owned by, managed by, assigned to, attested by), comments, work
notes, incident and change descriptions, and any custom column. Only the named
columns are requested, and the saved data is projected from them, so a column
the instance returns anyway never reaches the blueprint.

## Audience

New connections save snapshots for blueprint editors only. Choose **All
Blueprint readers** only when the class, ownership, relationships and, in
Detailed mode, the addresses and serials are appropriate for everyone who can
read the blueprint. Changing the audience applies to later refreshes and does
not recall copies already shared, exported or answered by AI.

## Refreshing and recovery

Snapshots become due for refresh after one day, which is a reminder rather than
automatic polling. A failed CI read keeps the previous snapshot and adds a
warning. A relationship read or task read that fails marks the panel
incomplete and says which table could not be read; the rest of the panel still
saves. A rate limit answered by ServiceNow with `Retry-After` is reported with
the number of seconds and is never retried in a loop.

---

# Blueprintr User Guide: GitHub
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/github

> Explain source, engineering work and deployment evidence beside the component in your diagram.

Link the repository behind a component to its Stratum. Choose the branch,
workflow, issue labels, deployment environment and source path that explain that
component. Your diagram stays the starting point; GitHub provides dated evidence
and links for further investigation.

## Connect repository reads

1. In the owning organisation or team, open **Settings → Continuum → Operational
   integrations → New integration**, and select **GitHub**. Continuum Link needs
   an Enterprise plan and `continuum_integrations.manage` on the connection
   owner. Linking a repository later also requires blueprint edit access.
2. Create a [fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
   for the intended resource owner and selected repositories. Obtain any required
   organisation approval. Use a dedicated integration credential with an expiry
   you can maintain. GitHub sign-in does not grant repository access to Link.
3. Enter a **Repository to verify**, as `owner/repository` or its GitHub HTTPS
   link. This is a verification sample; other linked repositories are checked
   when selected. An optional **Organization** restricts discovery and
   linking to that owner. Without one, the suggestion index keeps the names of
   every repository the token can list. Set an organization, or limit a
   fine-grained token to selected repositories, to narrow it.
4. Choose the reads to enable and grant their corresponding permissions below.
   Keep **Blueprint editors only** and **Summary** unless the wider content and
   audience are appropriate. Paste the token and choose **Connect & verify**.

| Read | Fine-grained repository permission | Default |
| --- | --- | --- |
| Repository identity and visibility | Metadata: read | Always |
| Open issues | Issues: read | Enabled |
| Workflow runs | Actions: read | Enabled |
| Open pull requests | Pull requests: read | Off |
| Deployment attempts and reported statuses | Deployments: read | Off |
| Latest branch/path commit and latest stable release | Contents: read | Off |

Contents permission also grants access to code, so turn it on only for the
commit and release rows. Link does not create issues, run workflows or change
the repository. Verification checks each enabled read, not only that the token
is valid. Empty accessible lists
are valid. This path supports **GitHub.com**; GitHub Enterprise Server and
GHE.com are not supported. See GitHub's
[permission reference](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens).

## Choose the context for a component

Save the blueprint and open **Continuum Link** from the Stratum's **+ Add tab**
menu. Search a repository name, paste `owner/repository`, or paste its GitHub.com
URL. A child URL such as an issue or pull request selects its containing
repository, not an individual work item. Scan and Suggest also propose
repository links for you to review.

Open **Choose the context for this component** before linking:

| Selection | What it means |
| --- | --- |
| Branch | Filters workflow runs and PR base branches. A known default branch is prefilled. Clearing it includes all workflow branches and PR bases; commit reads then use the default branch. |
| Workflow ID or filename | Selects the workflow whose result matters, for example `deploy.yml`. Without it, recent runs from different workflows are neutral repository context. |
| Deployment environment | Shows recorded deployment attempts for an exact environment such as `production`. Blank includes all environments. |
| Issue and PR labels | Every comma-separated label must match. Counts describe the retrieved matching scope. |
| Source directory or file | Links to the component's code and scopes the optional latest commit. It does not filter PRs, workflows or deployments. |

One connection can bind one repository/context to a Stratum. Re-select and link
it to change the context. The repository's numeric ID protects against an old
name being reused for a different repository. An old link without sufficient
identity evidence asks you to re-select before it can refresh.

## Read the evidence

| Task | How the tab helps |
| --- | --- |
| Explain a service | Shows its source path and branch, scoped open work and the selected workflow beside the service's architecture. Open GitHub for code, reviews, checks, comments and logs. |
| Review a release | Compares branch commit, CI result, recorded deployment attempts and GitHub's latest stable release. These are separate facts. A successful workflow or published release does not prove what is serving production or that the runtime is healthy. |
| Act on a diagram review | Create a GitHub follow-up from the Stratum, review the destination and text, and keep a link to the created issue beside it. |

Issues and pull requests appear separately. GitHub's repository-wide open count
is explicitly labelled **issues + PRs**. Open-work lists retrieve up to 300
records per section and display at most ten; coverage distinguishes exact
matching counts, bounded samples and unavailable reads. Run history shows up
to ten entries; deployment evidence shows up to three attempts and their latest
reported statuses. GitHub's issue-list retrieval limit includes PR records that
are removed from the issue section. PR label counts are exact only when the
queried PR list was retrieved in full. Missing information is not a healthy zero.

Opening the tab shows a saved snapshot. Use the circular-arrows button to fetch
again. After fifteen minutes the snapshot asks for a refresh; it does not poll.
If repository identity or metadata cannot be read safely, the previous snapshot
is preserved. If an enabled issue, workflow or optional section fails, the new
snapshot marks that section partial or unavailable; it does not present old
section values with a new timestamp.

Summary retains identity, visibility, states, scope and links but omits work
titles and descriptions. Detailed adds repository descriptions, issue/PR titles
and workflow names. Neither mode imports issue bodies, comments, commit
messages, personal identities, workflow logs, deployment payloads or release notes.

## Create and recover a follow-up

An organisation administrator with `webhook.manage` configures a separate
**GitHub Issues** destination by choosing its card in **Settings → Continuum**.
Choose the owner and repository and supply a separate fine-grained token with
**Metadata: read** and **Issues: read and write**. Optional existing labels need
repository push access. **Verify without creating an issue** checks access and
configuration; only a real creation can prove that GitHub accepts the write.

An editor who also has the organisation's `webhook.manage` permission can choose
**GitHub follow-up** on a saved Stratum, review
the issue title, description, repository visibility and source link, and create
the issue. Repository readers may differ from blueprint readers. Only the
reviewed issue text, source title/link and delivery reference are sent. The outcome and issue link
remain available from that Stratum.

GitHub Issues belongs to the **Webhooks & workflow** family advertised for Team.
Its organisation permissions are separate from the Enterprise plan required for
Link reads.

New destinations are manual-only. Optional subscriptions cover blueprint
publication and review submission, approval and rejection. They send a minimal
event summary, not arbitrary blueprint content or review comments. Existing
destinations must verify and save once to establish repository identity.

Delivery history distinguishes queued, retrying, failed, successful and unknown
outcomes. Safe retries are scheduled. An interrupted create with an unknown
outcome is not blindly repeated: find the issue in GitHub and reconcile it by
issue number in delivery history. Older one-shot deliveries are not replayed
automatically.

## Sharing, recovery and other GitHub paths

Newly fetched Link data defaults to blueprint editors, including when an older
connection has no audience setting. Choosing **All Blueprint readers** makes
approved snapshots available to everyone who can read the blueprint, including
anonymous public readers, embeds, exports and configured search/AI features.
GitHub does not re-authorise each Blueprintr reader. A source link still requires
that person's own GitHub access.

Settings apply on the next fetch. They do not rewrite earlier snapshots,
versions, templates, exports or distributed copies. Unlinking or revoking a
token cannot recall those copies. Review content before sharing it.

Use **Configure** to adjust permissions/content and **Verify & replace** to
rotate a token. A replacement must retain access to existing linked repository
IDs and enabled reads before it replaces the working token. For access errors,
check repository selection, token expiry, organisation approval and SSO. For
rate limits, wait before retrying. **Suspend** stops new searches and refreshes;
unlink tabs before deleting a Link connection.

[Folium repository sync](/foliums/blueprintr-user-guide/foliums/repo-sync) is a
separate docs-as-code path, configured on an individual Folium. Review the exact
destination and selected pages before pushing; draft and hidden pages start
unselected. GitHub sign-in is another independent path and grants no Link,
issue-creation or Folium-sync permissions.

---

# Blueprintr User Guide: Alerts on a diagram
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/alerting

> Where alert state appears when a monitoring platform is linked, and where it does not.

Alert state from a linked monitoring platform appears on a stratum, as a saved
panel. It never appears on the drawing.

## On the stratum, not the canvas

> [!IMPORTANT]
> [Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link)
> cannot change a shape. Alert counts, severities and acknowledgement state are
> rendered into the tab you bound. Nothing reaches the canvas.

Shape outlines do change, but they come from
[Continuum Cloud](/foliums/blueprintr-user-guide/continuum/continuum-cloud)
discovery, not from monitoring. A red outline means the cloud provider reports
the resource offline, not that something is alerting. The full vocabulary is on
[keeping diagrams true](/foliums/blueprintr-user-guide/continuum/keeping-diagrams-true).

To see where in a system a problem sits, open the stratum for the component. The
diagram gives it its context; the panel gives it its state.

## Who can read it

The saved panel travels with the stratum. It is stored in the blueprint's own
record and in backups, and unless the connector restricts its audience to editors
it reaches everyone who can read the blueprint, including anonymous readers of a
public blueprint, embeds and exports.

Among the alerting and monitoring connectors, only Datadog, LogicMonitor, Auvik
and Rootly can restrict it, and a new connection to any of them starts
restricted. A Datadog or LogicMonitor connection created before the setting
existed stays reader-visible until an administrator changes it. Check the
connector before linking an alerting platform to anything published. See
[Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link).

## What a panel is

A dated snapshot, fetched when an editor asked for it. Opening the tab displays
what was saved and contacts nothing.

Read the banner above it before acting on the numbers. It says whether the
snapshot is current, due a refresh, incomplete, failed or paused. An incomplete
snapshot reports lower bounds, and a failed read is labelled unavailable rather
than shown as zero.

Counts describe what a platform reported at a stated time. They are not a
statement that a component is healthy now.

## Finding which platform knows about a shape

Each aid needs an Enterprise plan, edit access, and at least one verified
connection. Below that they refuse or do not appear.

**Suggest Continuum Links** under a Vellum diagram's bottom bar checks every shape
on the blueprint against Blueprintr's index of your connections, and the button
says how many matches it found before you open it. The same button on a stratum's
tab strip checks one stratum: its linked shape, its title, and hostnames,
addresses or URLs in its text. **Check live** in either dialog asks the
connections themselves instead, a batch of shapes at a time. Matches with strong,
unambiguous evidence start ticked. The rest are listed with the reason they were
held back, which includes an index that is out of date, incomplete, or limited
to some object types. A
connection a stratum already links is not suggested for that stratum again. See
[Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link) for
what the index stores and when it updates.

Right-click a shape in a saved diagram and choose **Suggest integrations…**. It
scores matches from the shape's identifiers, its icon, and whether a connected
shape is already bound to the same platform.

On **Resources & Strata** in the blueprint editor, the scan button reads **Scan ·
N integrations** once connections exist. It reads stratum titles, file content,
tab bodies and shape labels, up to 200 identifiers per scan.

All of them propose candidates for review and attach nothing until you add or
apply them.

> [!NOTE]
> None of them compares your estate against your monitoring. Continuum does not
> report which resources have no alerting on them.

## Not a monitoring system

Blueprintr does not evaluate conditions, hold thresholds, or page anyone. It
reads state from the system that does, and links back to it for anything you need
to act on.

---

# Blueprintr User Guide: Continuum Local
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent

> The on-premise agent that lets Continuum Link read monitoring systems Blueprintr cannot reach.

Continuum Local is an agent you run inside your own network. It exists so
[Continuum Link](/foliums/blueprintr-user-guide/continuum/continuum-link) can
read monitoring systems that are never exposed to the internet, and so you can
sweep your network for SNMP devices.

It is the on-premise half of Continuum Link and sits behind the same gate: the
organisation that owns the agent needs an Enterprise plan (a team's agent uses
its parent organisation's plan), and you need `continuum_integrations.manage` on
that organisation or team.

> [!IMPORTANT]
> Continuum Local is separate from
> [Continuum Cloud](/foliums/blueprintr-user-guide/continuum/continuum-cloud).
> It serves connector panels on strata and network sweeps, and discovers no
> cloud resources.

> [!TILES 3]
>
> === [Installing](/foliums/blueprintr-user-guide/continuum/local-agent/install)
>
> Prerequisites, sizing, each platform, and enrolling the agent.
>
> === [Network requirements](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements)
>
> Outbound connections, ports, proxies and TLS inspection.
>
> === [Configuration reference](/foliums/blueprintr-user-guide/continuum/local-agent/configuration)
>
> Every setting in `config.json`, secret references and the check command.
>
> === [Security model](/foliums/blueprintr-user-guide/continuum/local-agent/security)
>
> What the agent enforces, and what Blueprintr stores, who sees it and for how long.
>
> === [Network discovery](/foliums/blueprintr-user-guide/continuum/local-agent/network-discovery)
>
> What an SNMP sweep reads, its limits, and running and reviewing sweeps.
>
> === [Releases and verification](/foliums/blueprintr-user-guide/continuum/local-agent/releases)
>
> Versions, signatures, SBOMs and which releases are supported.
>
> === [Upgrading and removing](/foliums/blueprintr-user-guide/continuum/local-agent/upgrade-and-uninstall)
>
> Upgrades, rollbacks, credential rotation and uninstalling.
>
> === [Troubleshooting](/foliums/blueprintr-user-guide/continuum/local-agent/troubleshooting)
>
> Logs, error codes and common failures.
>
> === [Questions and limitations](/foliums/blueprintr-user-guide/continuum/local-agent/faq)
>
> Air-gapped networks, redundancy, a lapsed plan and other limits.

## What it serves

It serves SolarWinds Orion, Zabbix, PRTG Network Monitor, Checkmk, Icinga 2,
ManageEngine OpManager, WhatsUp Gold, NetBox, Infoblox and Veeam Backup &
Replication, whose fields and panels the
[connector reference](/foliums/blueprintr-user-guide/continuum/connector-reference)
lists. Each appears in the connector list but stays disabled until an
agent that can serve it is online. The label says why: set up an agent, your
agent is offline, or upgrade your agent. An agent counts as online when it has
checked in within about ninety seconds.

Each one needs a dedicated account that can only read. The credential parts are
the names you use under `credential` in the agent's configuration, or in the
**send credentials** form.

| Connector | Credential parts | Least-privilege account | Default port | Certificate |
| --- | --- | --- | --- | --- |
| SolarWinds Orion | `username`, `password` | An Orion account with no administrator, node management or unmanage rights | 17774 (SWIS) | Self-signed on install |
| Zabbix | `token` | A user whose role type is User, in a group with Read on the host groups to show (Zabbix 6.0 LTS and later) | 443 | Depends on the install |
| PRTG Network Monitor | `token` | An API key with Read access for a Read-only user (PRTG 22.3.79 and later) | 443 | Self-signed on install |
| Checkmk | `username`, `password` | An automation user whose role is copied from Guest, plus Read access to all hosts and folders | 443 | Depends on the install |
| Icinga 2 | `username`, `password` | An ApiUser with only `objects/query/Host` and `objects/query/Service` (and `filter-expression` where enforced) | 5665 | Icinga's own CA |
| ManageEngine OpManager | `token` | An API key with Read access only, or on builds before 12.8.721 a read-only Operator's key | 8060. Write it in the URL: without a port, the connector uses 443 | Self-signed on install |
| WhatsUp Gold | `username`, `password` | A read-only user that can read the Entire Network device group | 9644 | Depends on the install |
| NetBox | `token` | A user whose only permission is view on devices, interfaces, IP addresses, virtual machines and VM interfaces, with Write enabled off on the token (NetBox 4.0 and later) | 443 | Depends on the install |
| Infoblox | `username`, `password` | A NIOS admin in its own group that may use the API, with read-only permission on the networks, DNS views, host records and DHCP data to show and no superuser rights | 443 | Issued to www.infoblox.com: replace it first |
| Veeam Backup & Replication | `username`, `password` | An account with only the Veeam Backup Viewer role, marked as a service account if multi-factor authentication is on (version 12 and later) | 9419 | Self-signed on install |

A port you give in the connector's URL replaces the default, including 443 for
a reverse proxy. WhatsUp Gold and Veeam Backup & Replication trade the username
and password for an access token, which the agent keeps: Blueprintr only sees a
stand-in for it. They need agent 0.2.0 or later, and the connector list says to
upgrade an older agent.

## How it reaches Blueprintr

The agent dials out over HTTPS on port 443. Nothing connects inward, so no
inbound firewall rule is needed. Allow outbound HTTPS from the agent's host to
`blueprintr.io` and `agents.blueprintr.io`. The agent keeps a connection open to
`agents.blueprintr.io` when Blueprintr offers it, polls at least once a minute,
and falls back to polling `blueprintr.io` directly if that connection stops
answering. A proxy for this traffic is set with `proxy` and `noProxy` in the
agent's [configuration](/foliums/blueprintr-user-guide/continuum/local-agent/configuration).

> [!NOTE]
> It is for private and firewalled estates, not air-gapped ones. A host with no
> outbound path to Blueprintr cannot run it.

There is no schedule of its own for connectors. A job is created when an editor
refreshes a linked tab, and a queued job expires if no agent claims it.

Blueprintr's suggestion index never covers these connectors, so nothing about
your on-premise systems is copied to Blueprintr ahead of time. **Suggest
Continuum Links** reaches them only when an editor chooses **Check live**, and
then through the agent, like any other request.

## Getting the agent

Download it from the [Continuum Local download page](https://blueprintr.io/download/continuum-local)
while signed in to an account on an Enterprise plan. The Continuum Local panel
links there too. The page offers the current release and a few earlier ones, so
you can install the version your change control approved or roll back to one.

[Installing](/foliums/blueprintr-user-guide/continuum/local-agent/install)
covers packages for Debian and Ubuntu, RHEL, Rocky and Alma, and Windows Server,
each with its own runtime, plus a container image, a Helm chart and a single
file for a host with Node.js 24. Every release is signed, and
[Releases and verification](/foliums/blueprintr-user-guide/continuum/local-agent/releases)
gives the signing identity to check it against.

## Registering an agent

Register it yourself from **Settings → Continuum → Continuum Local** on the
organisation or team.

> [!STEPS]
>
> === Add an agent
>
> Name it, and Blueprintr issues an enrolment token.
>
> === Copy the token now
>
> It is shown exactly once, can be used once, and expires after 24 hours. There is
> no way to retrieve it afterwards. An expired, spent or revoked token fails
> enrolment with the same message: rather than diagnosing it, issue a new token,
> or for a revoked agent create a new agent.
>
> === Put it in the agent's configuration
>
> Set it as `enrollmentToken` in the agent's `config.json`, run
> `continuum-local check` to test the file, start the agent, then delete that
> line. It is spent once used.
>
> === Copy the connector configuration
>
> The panel prints a configuration block for each on-premise connection, keyed
> by the connection's ID. The ID is shown only in this panel.

**New token** and **Re-enroll** issue a replacement token and cancel the
previous unused one. Neither works on a revoked agent: create a new agent
instead. **Revoke** cuts an agent off at once, including a connection it has
open.

If the organisation's plan has lapsed, enrolment is refused with a message that
says so, and the token is not spent. Once an owner renews the plan, restart the
agent and it enrols with the same token while the token is still valid.

After a lapse the panel still lists the agents, marked as paused, so you can
take them out of service: **Revoke**, **Delete** (which also deletes the
agent's network sweep results) and **remove from agent** for credentials sent
from Blueprintr. Nothing else is offered until the plan is active again. A
paused agent's polls are refused, so **remove from agent** usually reports it
offline. Remove those credentials on the agent's machine instead, by deleting
its state as described under
[Uninstall](/foliums/blueprintr-user-guide/continuum/local-agent/upgrade-and-uninstall#uninstall).

## Credentials

Blueprintr never stores a credential for an on-premise system. The
[security model](/foliums/blueprintr-user-guide/continuum/local-agent/security#where-credentials-are-kept)
lists where the agent keeps each kind. Blueprintr cannot read, export or recover a credential, and cannot help
you rotate one. Rotation happens in the agent and in the monitored system.

| Where you set it | How |
| --- | --- |
| In the agent's configuration | Edit `config.json` on the agent's own machine. The values never leave your network. This is the default. |
| From Blueprintr | Set `"allowRemoteCredentials": true` in the agent's configuration and restart it. The agent needs version 0.2.0 or later. The Continuum Local panel then offers **send credentials** for each on-premise connection. |

A credential sent from Blueprintr passes through Blueprintr over an encrypted
connection to the running agent, which keeps it in its own state directory.
Blueprintr keeps no copy, so nothing is queued: the agent has to be online and
connected to `agents.blueprintr.io` at the time, and the panel shows it as
"connected through the gateway". An agent that is only polling cannot receive a
credential, and where Blueprintr does not offer the gateway, the panel says
sending credentials is not set up. In either case, put the credential in
`config.json`.

- `remoteCredentialScope` in the agent's configuration limits which hosts
  Blueprintr may configure. Certificate settings sent from Blueprintr are
  refused unless that scope sets `allowTlsOverrides`.
- A connection set in `config.json` always wins. Blueprintr can neither replace
  nor remove it.
- **remove from agent** deletes a credential Blueprintr sent. Deleting the
  connection in Blueprintr removes it from the agent too. Both need the agent
  online and connected to the gateway, so remove credentials before you revoke
  or delete an agent.

Revoking or deleting an agent in Blueprintr, or uninstalling it, does not delete
what is on its machine: `config.json` and any credentials sent from Blueprintr
stay there until you delete the agent's configuration and state, as
[Uninstall](/foliums/blueprintr-user-guide/continuum/local-agent/upgrade-and-uninstall#uninstall)
describes for each platform.

Wherever the credential is set, Blueprintr runs the connector with unguessable
placeholder values standing in for it, and tells the agent which parts to
replace with local values. The agent refuses to send a request if a placeholder
survives into it, and for a credential set from Blueprintr it will only reach
the host that integration is configured for.

## Read-only by default

The agent sends only requests it recognises as reads for that product, by the
rules of its
[read-only guard](/foliums/blueprintr-user-guide/continuum/local-agent/security#the-read-only-guard).
Anything else is refused with `operation_not_allowed`, and nothing is changed.
Blueprintr's message says which check refused the request, and
[Operation not allowed](/foliums/blueprintr-user-guide/continuum/local-agent/troubleshooting#operation-not-allowed)
gives the fix for each.

Setting `"allowWriteOperations": true` on one integration in `config.json` lifts
the guard for that integration only. Blueprintr can never set it. Upgrade the
agent first, and turn it on only for a write you have confirmed you want to
allow.

## Network sweeps

With a `discovery` block in its configuration, an agent can
[sweep your network](/foliums/blueprintr-user-guide/continuum/local-agent/network-discovery)
for SNMP devices. Start one from **Network sweeps** below the Continuum Local
panel, or schedule one daily or weekly. The agent sweeps only the ranges in its
own `discovery` block: Blueprintr can narrow a sweep to some of them but never
widen it, and the SNMP credentials stay on the agent. An agent runs one sweep at
a time.

Blueprintr keeps the devices, ports and links each sweep finds for 90 days from
when the sweep starts, apart from each agent's latest complete sweep, which is
kept until a newer one completes.

## Certificates

The agent refuses a certificate it cannot verify. Orion, PRTG, OpManager and Veeam Backup & Replication install with a
self-signed certificate, and Icinga 2 uses its own certificate authority
(`ca.crt` in `/var/lib/icinga2/certs`). For Checkmk, Zabbix, WhatsUp Gold and
NetBox it depends on how they were installed; NetBox serves no HTTPS of its own,
so it is whatever sits in front of it. Give the agent that certificate, or your
internal authority's, as `caFile` rather than disabling certificate checking.

Infoblox NIOS is the exception. It installs with a certificate issued to
www.infoblox.com, so `caFile` alone cannot verify it for your grid's address.
Replace the grid's certificate first: in Grid Manager, go to **Grid > Grid
Manager > Members**, select the Grid Master, and choose **Certificates > HTTPS
Cert > Generate Self-signed Certificate** for the address the agent uses (an IP
address goes in as a subject alternative name; on an HA pair, use the address of
the VIP), or install one from your own certificate authority. Then give the agent
that certificate as `caFile`. Turn checking off with `allowInsecureTls` only as a
last resort.

## Compatibility

The agent advertises what it can do, and Blueprintr sends only work that matches.
A newer kind of job is invisible to an older agent rather than breaking it, so
agents upgrade on your schedule rather than Blueprintr's. The panel shows
**Update available** when a newer release exists. Before version 1.0 only the
[latest release is supported](/foliums/blueprintr-user-guide/continuum/local-agent/releases#supported-versions-and-compatibility).

## Troubleshooting

When an agent has not been heard from for 15 minutes, Blueprintr emails the
owners and admins of the organisation that owns it, and of the team for a team's
agent. On the agent's host, run `continuum-local check`, then read the agent's
log and look up any error code in
[Troubleshooting](/foliums/blueprintr-user-guide/continuum/local-agent/troubleshooting),
which also says where each install writes its log.

---

# Blueprintr User Guide: Installing Continuum Local
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/install

> Prerequisites, sizing, installation on Linux, Windows, Docker, Kubernetes or a Node.js host, and enrolling the agent with Blueprintr.

Continuum Local ships as Debian and RHEL packages, a Windows installer, a
container image, a Helm chart, and a single JavaScript file for a host that
already runs Node.js. Every format runs the same agent file. Install the format
your estate already manages, give it an enrolment token from Blueprintr, run
`continuum-local check`, then start it.

> [!NOTE]
> The packages, the Windows installer, the container image and the Helm chart
> are published from release 0.2.0. Release 0.1.0 is the JavaScript file only.

## Before you start

| Requirement | Detail |
| --- | --- |
| Plan and permission | The organisation that owns the agent is on Enterprise (a team's agent uses its parent organisation's plan), and you have `continuum_integrations.manage` on that organisation or team. |
| Outbound HTTPS | Port 443 from the agent's host to `blueprintr.io` and `agents.blueprintr.io`, directly or through a proxy, as [network requirements](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements) describes. The agent accepts no inbound connections. |
| Routes to your systems | From the agent's host to each monitoring system on its API port (see the [connector table](/foliums/blueprintr-user-guide/continuum/local-agent#what-it-serves)), and UDP 161 to any device you sweep over SNMP. |
| Linux packages | systemd, and glibc 2.28 or later (RHEL 8, Debian 10, Ubuntu 20.04 or newer), on x86-64 or arm64. |
| Windows | 64-bit Windows Server. |
| Containers | linux/amd64 or linux/arm64. |
| Node.js host | Node.js 24 or later. Every other format includes its own runtime. |

### Sizing

The agent runs up to four relay and probe jobs at a time (`maxConcurrentJobs`,
1 to 16) and one network sweep alongside them. It ships with these limits:

| Format | Limits as shipped |
| --- | --- |
| Linux packages | Memory capped at 512 MB by the systemd unit (`MemoryMax`). Raise it with `sudo systemctl edit continuum-local`. |
| Helm chart | Requests 50m CPU and 96 MiB memory, memory limit 256 MiB, no CPU limit, and a 64 MiB PersistentVolumeClaim for state. |

Run one copy of each agent. Two processes sharing one enrolled identity take
work from the same queue, which adds no redundancy. For another site or network
segment, create another agent. An organisation or team may register up to 25
agents, and a revoked agent counts until you delete it.

## Download and verify

Download from the [download page](https://blueprintr.io/download/continuum-local)
while signed in to an account on an Enterprise plan; for anyone else the page
reports not found. Check the signature before you install. The page prints the
commands for the release you are viewing, and
[Releases and verification](/foliums/blueprintr-user-guide/continuum/local-agent/releases)
explains them.

The commands below use `$V` for the version you downloaded, for example
`V=0.2.0`.

## Linux packages

### Debian and Ubuntu

```bash
sudo apt install ./continuum-local_${V}_amd64.deb
sudo cp /etc/continuum-local/config.example.json /etc/continuum-local/config.json
sudo -e /etc/continuum-local/config.json
sudo chown root:continuum-local /etc/continuum-local/config.json
sudo chmod 640 /etc/continuum-local/config.json
sudo continuum-local check /etc/continuum-local/config.json
sudo systemctl enable --now continuum-local
```

On arm64, install the `_arm64.deb`. What to put in `config.json` is under
[Enrol the agent](#enrol-the-agent). The package creates a `continuum-local`
system account and a systemd unit, and leaves the service disabled until you
enable it.

### RHEL, Rocky and Alma

```bash
sudo dnf install ./continuum-local-${V}-1.x86_64.rpm
```

On arm64, install the `.aarch64.rpm`. Then follow the Debian steps from `cp`
onwards.

### What the packages install

| Path | Contents |
| --- | --- |
| `/etc/continuum-local/config.json` | Your configuration, which you create. Owned by `root:continuum-local` with mode 0640, so the service reads it and cannot change it. |
| `/etc/continuum-local/environment` | Environment variables for the service. Root only (0600), and kept on upgrade. |
| `/var/lib/continuum-local` | The state directory: the enrolled identity and any credentials sent from Blueprintr. Mode 0700. |
| `/usr/lib/continuum-local` | The agent and its Node.js runtime. |
| `/usr/bin/continuum-local` | The command for `check`, `discover`, `probe` and `walk`. |

The service runs as the unprivileged `continuum-local` account, with no
capabilities and a read-only filesystem apart from its state directory. Its
logs are in the journal: `journalctl -u continuum-local`.

Run the `continuum-local` command with `sudo`. As root it reads
`/etc/continuum-local/environment` the way systemd does, then switches to the
`continuum-local` account, so `check` sees the same proxy, certificates and file
permissions as the service.

### Proxy settings

Put proxy variables in the environment file, or set `proxy` and `noProxy` in
`config.json`, which take precedence:

```bash
sudo -e /etc/continuum-local/environment
```

```text
HTTPS_PROXY=http://proxy.corp.example:3128
NO_PROXY=localhost,.corp.example
```

```bash
sudo systemctl restart continuum-local
```

The agent sends only its traffic to Blueprintr through the proxy. Its
connections to your own systems stay direct. If the proxy re-signs TLS, set the
proxy's root certificate as `extraCaFile` in `config.json`: the agent trusts that
file for Blueprintr and never for your own systems. Variables used in `env:`
references also go in the environment file, such as `SOLARWINDS_PASSWORD` for
`"password": "env:SOLARWINDS_PASSWORD"`.

## Windows

> [!STEPS]
>
> === Run the installer
>
> Run `continuum-local-<version>-x64.msi` as an administrator. It installs to
> `C:\Program Files\Continuum Local` and registers the **Blueprintr Continuum
> Local** service (`ContinuumLocal`), which runs as `LocalService`. A first
> install leaves the service stopped and set to Manual.
>
> === Create the configuration
>
> In an elevated PowerShell, copy the example and edit it as described under
> [Enrol the agent](#enrol-the-agent):
>
> ```powershell
> Copy-Item "C:\Program Files\Continuum Local\config.example.json" `
>   "C:\ProgramData\Continuum Local\config.json"
> notepad "C:\ProgramData\Continuum Local\config.json"
> ```
>
> === Check it
>
> ```powershell
> & "C:\Program Files\Continuum Local\runtime\node.exe" `
>   "C:\Program Files\Continuum Local\continuum-local.mjs" `
>   check "C:\ProgramData\Continuum Local\config.json"
> ```
>
> === Enable and start the service
>
> ```powershell
> Set-Service -Name ContinuumLocal -StartupType Automatic
> Start-Service -Name ContinuumLocal
> ```

The installer gives `C:\ProgramData\Continuum Local` its own access list: the
service reads `config.json` but cannot change it, and writes only to `state\`
and `logs\`. Service logs are in `C:\ProgramData\Continuum Local\logs`. Set a
proxy with `proxy` and `noProxy` in `config.json`, because environment variables
added to the service are replaced on every upgrade.

> [!NOTE]
> The installer and its service wrapper, WinSW, are not Authenticode-signed.
> Check the `.msi` against the signed `SHA256SUMS` before you run it. The Windows
> installer has not been run on a customer's server, so treat the first install
> as a test.

## Docker

```bash
docker run -d --name continuum-local --restart=unless-stopped \
  -v /etc/continuum-local:/etc/continuum-local:ro \
  -v continuum-local-state:/var/lib/continuum-local \
  ghcr.io/blueprintr-io/continuum-local:$V
```

The image runs as the unprivileged `node` user (uid 1000) and reads
`/etc/continuum-local/config.json`, so uid 1000 needs read access to that file
on the host. The `continuum-local-state` volume keeps the enrolled identity.
Without it, a new container enrols again and fails, because the token is
already spent. Check the configuration with the same mounts:

```bash
docker run --rm \
  -v /etc/continuum-local:/etc/continuum-local:ro \
  -v continuum-local-state:/var/lib/continuum-local \
  ghcr.io/blueprintr-io/continuum-local:$V check
```

Give a proxy as `-e HTTPS_PROXY=... -e NO_PROXY=...`, or in the configuration.
Once you have verified the image, run it by the digest that `cosign verify`
prints: a tag can be moved, a digest cannot.

## Kubernetes

```bash
kubectl create secret generic continuum-local-config --from-file=config.json
helm install agent oci://ghcr.io/blueprintr-io/charts/continuum-local \
  --version $V --set existingSecret=continuum-local-config
```

To install from a file instead, use `continuum-local-helm-chart-<version>.tgz`
from the download page in place of the `oci://` address.

The chart runs one replica with the `Recreate` strategy, as a non-root user with
a read-only root filesystem, and creates no Service or Ingress. Its main values:

| Value | Default | Meaning |
| --- | --- | --- |
| `existingSecret` | none | A Secret with a `config.json` key. Keeps credentials out of your values file. |
| `config` | `{}` | The configuration inline, instead of a Secret. It puts credentials in your values file. |
| `configRevision` | none | Any string. Changing it restarts the pod, which Kubernetes does not do when a Secret changes. |
| `persistence.enabled` | `true` | Keeps the enrolled identity on a PersistentVolumeClaim of `persistence.size` (64Mi). With it off, state is lost whenever the pod is replaced, and the next start fails because the token is already spent. |
| `persistence.storageClass`, `persistence.existingClaim` | none | Your own storage class or claim. |
| `image.repository`, `imagePullSecrets` | `ghcr.io/blueprintr-io/continuum-local`, none | For a registry mirror. `image.tag` defaults to the chart's version. |
| `extraEnv`, `extraVolumes`, `extraVolumeMounts` | none | Proxy variables and extra CA files. The chart's `values.yaml` has examples. |

Without `existingSecret` or `config`, the agent does not start. After you edit
the Secret, restart the agent:

```bash
kubectl rollout restart deployment/agent-continuum-local
```

## A host with Node.js

Requires Node.js 24 or later. Download `continuum-local-<version>.mjs`, write
`config.json` beside it, owned by the account that runs the agent with mode
0600, then:

```bash
node continuum-local-$V.mjs check ./config.json
node continuum-local-$V.mjs ./config.json
```

Run it under whatever supervises long-running processes on that host. It exits
cleanly on SIGTERM or SIGINT.

## Configuration and state locations

| Install | Configuration | State directory |
| --- | --- | --- |
| Debian, Ubuntu, RHEL, Rocky, Alma | `/etc/continuum-local/config.json` | `/var/lib/continuum-local` |
| Windows | `C:\ProgramData\Continuum Local\config.json` | `C:\ProgramData\Continuum Local\state` |
| Docker | `/etc/continuum-local/config.json`, mounted from the host | The volume at `/var/lib/continuum-local` |
| Kubernetes | The Secret, mounted at `/etc/continuum-local/config.json` | The PersistentVolumeClaim, at `/var/lib/continuum-local` |
| Node.js host | The path you pass | See below |

The state directory contains the enrolled identity (`agent-state.json`, mode
0600) and any integrations configured from Blueprintr. `statePath` in the
configuration overrides it on every format. Without it, the agent uses
`CONTINUUM_LOCAL_STATE_DIR` when set, then a systemd `StateDirectory=`, then
`%ProgramData%\Continuum Local\state` on Windows, then
`/var/lib/continuum-local` for `/etc/continuum-local/config.json` on Linux, and
otherwise the configuration file's own directory.

## Enrol the agent

> [!STEPS]
>
> === Create the agent in Blueprintr
>
> In **Settings → Continuum** on the organisation or team, under **Continuum
> Local**, choose **Add an agent**, name it and choose **Create**.
>
> === Copy the token
>
> Choose **Copy enrollment token**. The token is shown once, works once and
> expires after 24 hours.
>
> === Put it in the configuration
>
> The smallest configuration that enrols:
>
> ```json
> {
>   "apexUrl": "https://blueprintr.io",
>   "displayName": "DC1 agent",
>   "enrollmentToken": "the token you copied"
> }
> ```
>
> `enrollmentToken` also accepts a reference such as `"env:CL_TOKEN"` or
> `"file:/etc/continuum-local/token"`. If you started from
> `config.example.json`, delete the sample proxy, integrations and discovery
> block you do not use, since they contain example hosts and ranges.
>
> === Check and start
>
> Run `check` as shown for your format, then start the agent. It confirms its
> state directory is writable before it sends the token, then exchanges the token
> for its own credential and writes that to the state directory.
>
> === Confirm it is online
>
> Within a minute of starting, the agent's status in the panel changes from
> **Waiting to be installed** to **Online**, followed by "connected through the
> gateway" or "polling (no gateway connection)". The agent polls when it has no
> gateway connection, so both states serve work.
>
> === Remove the token
>
> Delete the `enrollmentToken` line. It is spent, and the agent logs a reminder
> at each start while the line is there.

An expired, spent or revoked token gets the same refusal. Issue another with
**New token** on the agent, or for a revoked agent, create a new agent. If the
owning organisation's plan is inactive, enrolment is refused with a message
that says so, and the token is not spent.

Next, add your on-premise connections in Blueprintr and copy the configuration
block the panel prints for each into `integrations`: see
[Continuum Local](/foliums/blueprintr-user-guide/continuum/local-agent). Every
setting is in the
[configuration reference](/foliums/blueprintr-user-guide/continuum/local-agent/configuration).

## Running the check

Run [`continuum-local check`](/foliums/blueprintr-user-guide/continuum/local-agent/configuration#the-check-command)
on every new install, after every configuration change and before you contact
support. It tests the configuration, the state directory, the certificate
roots, the route to Blueprintr and a TLS handshake with each integration host,
without enrolling or spending the token.

---

# Blueprintr User Guide: Network requirements
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements

> What Continuum Local connects to and on which ports, and how to run it behind a proxy or a TLS-inspecting firewall.

Continuum Local makes outbound connections only. It listens on no port, so it
needs no inbound firewall rule and no public address. The Helm chart creates no
Service and no Ingress.

## Outbound connections

| Destination | Port | Protocol | Purpose |
| --- | --- | --- | --- |
| `blueprintr.io` | TCP 443 | HTTPS | Enrolment, and polling for work whenever the agent is not using the gateway |
| `agents.blueprintr.io` | TCP 443 | HTTPS, and WebSocket over TLS (WSS) | The agent gateway: a WebSocket that tells the agent when work is waiting, plus its polls and sweep uploads while it uses the gateway |
| Each on-premise system | TCP, the port in its URL in Blueprintr (defaults below) | HTTPS | The read requests Continuum Link makes through the agent |
| Each address in `discovery.cidrs` | UDP 161, or `discovery.port` | SNMP | Network sweeps. Only with a `discovery` block |
| A host in an integration's `allowedHosts` | UDP, the port the probe gives | SNMP | An SNMP probe of one device. Only with a `discovery` block |
| Your DNS resolvers | 53 | DNS | Resolving the hosts above, unless a proxy resolves the Blueprintr hosts for the agent |

An agent uses the gateway only after Blueprintr has advertised it, and polls
`blueprintr.io` before that. Allow both hosts, so the agent can move to the
gateway without a firewall change. The agent does not depend on the gateway.
If it cannot open the WebSocket, it keeps working by polling. If the gateway
stops answering polls, the agent polls `blueprintr.io` and tries the gateway
again every five minutes.

The agent never downloads or updates itself. You install each upgrade.

### On-premise systems

Allow TCP from the agent's host to each system's API port. A port you write in
the connector's URL in Blueprintr replaces the default.

| Connector | Default port |
| --- | --- |
| SolarWinds Orion | 17774 (SWIS) |
| Zabbix | 443 |
| PRTG Network Monitor | 443 |
| Checkmk | 443 |
| Icinga 2 | 5665 |
| ManageEngine OpManager | 8060. Write it in the URL: without a port, the connector uses 443 |
| WhatsUp Gold | 9644 |
| NetBox | 443 |
| Infoblox NIOS | 443 |
| Veeam Backup & Replication | 9419 |

`allowedHosts` in the agent's configuration matches host names only, and any
port on a listed host is allowed. Control ports with your firewall. The agent
follows at most three redirects, and checks each one against `allowedHosts`
again.

### Network sweeps

A sweep sends SNMP GET, GETNEXT and GETBULK requests over UDP from the agent's
host to port 161 on each address it probes, and needs the replies back. Sweeps
are IPv4 only, and the
[`discovery` settings](/foliums/blueprintr-user-guide/continuum/local-agent/configuration#discovery)
limit them. The agent sends at most `discovery.packetsPerSecond` packets a
second (50 by default), shared by every sweep and probe it runs. It does not use
ICMP or scan ports. Your intrusion detection sees SNMP requests from the agent's
address.

## Proxies

Traffic to Blueprintr can go through an HTTP or HTTPS proxy. Set `proxy` and
`noProxy` in `config.json`, or `HTTPS_PROXY` and `NO_PROXY` in the agent's
environment. The configuration file wins. Without it, the agent reads
`HTTPS_PROXY`, then `https_proxy`, then `HTTP_PROXY`, and `NO_PROXY`, then
`no_proxy`.

- Enrolment, polls, sweep uploads and the gateway WebSocket go through the
  proxy. It must allow a CONNECT tunnel to port 443 on both Blueprintr hosts.
- Connections to your on-premise systems and SNMP sweeps never use the proxy,
  whatever `HTTPS_PROXY` says, so an internal host name is never sent to it.
- SOCKS proxies are not supported.
- For a proxy that needs a user name and password, write
  `http://user:password@proxy.corp.example:3128`. The password is masked in
  every log line. Put the URL behind `env:` or `file:` to keep it out of
  `config.json`.
- A proxy needs Node.js 24 or later. The packages and the container include it.
  The bare bundle on an older Node.js refuses to start with a proxy configured,
  rather than going direct.

Where to put the setting:

| Install | Where |
| --- | --- |
| Debian, Ubuntu, RHEL, Rocky, Alma | `config.json`, or `/etc/continuum-local/environment`, which systemd reads as root before starting the agent. That file is mode 0600 because a proxy URL can contain a password |
| Windows | `config.json`. Environment variables added to the service are replaced by every upgrade, and a machine-wide `HTTPS_PROXY` reaches the service only after a reboot |
| Container | `config.json`, or `-e HTTPS_PROXY=... -e NO_PROXY=...` |
| Helm chart | `config.json`, or `extraEnv`. Read a URL that contains a password from a Secret with `valueFrom` |

## TLS-inspecting proxies

A proxy that re-signs TLS shows the agent its own certificate for
`blueprintr.io`, and the agent refuses it until it trusts the proxy's root.
Give the agent that root certificate, in PEM form, as `extraCaFile`. The agent
trusts that file for Blueprintr only, never for your on-premise systems,
because a proxy's root can sign a certificate for any name.

- `trustSystemCa`, on by default, trusts the operating system's certificate
  store as well. A proxy root already installed there works without
  `extraCaFile`.
- Avoid `NODE_EXTRA_CA_CERTS` for a proxy's root. Node.js reads it itself and
  trusts it for every connection, your on-premise systems included.
- A DER file is refused at start. Convert it with
  `openssl x509 -inform der -in proxy-root.cer -out proxy-root.pem`.
- A proxy that inspects TLS must also let the WebSocket upgrade to
  `agents.blueprintr.io` through. If it does not, the agent polls instead.

## Firewalls and allow-lists

- Allow the Blueprintr hosts by name. Blueprintr publishes no fixed IP
  addresses for `blueprintr.io` or `agents.blueprintr.io`, and the addresses
  behind them can change. A firewall or proxy that filters on DNS names or on the
  TLS server name can allow them.
- Requests to your monitoring systems come straight from the agent, never
  through the proxy. If a system limits its API to certain source addresses,
  add the address the agent's traffic leaves from.
- Devices that limit SNMP to named managers need the agent's address in that
  list.

## Checking the route

Run `continuum-local check` on the agent's host, with the command
[Troubleshooting](/foliums/blueprintr-user-guide/continuum/local-agent/troubleshooting)
gives for each platform. It resolves each Blueprintr host, opens a TCP
connection and a verified TLS handshake, through the proxy when one is set, and
does the same directly with every host an integration may reach, on port 443
unless you pass `--port`. It sends nothing beyond the handshake.

---

# Blueprintr User Guide: Configuration reference
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/configuration

> Every setting in the Continuum Local agent's config.json, with its type, default and limits, plus secret references, environment variables, logging and the check command.

The agent reads one JSON file, `config.json`, when it starts. The file is the
agent's security policy: it decides which integrations exist, which hosts each
may reach and which networks may be swept. The agent never writes to it, and a
change takes effect when the agent restarts.

| Install | Location |
| --- | --- |
| `.deb`, `.rpm` | `/etc/continuum-local/config.json` |
| `.msi` | `C:\ProgramData\Continuum Local\config.json` |
| Container | `/etc/continuum-local/config.json`, mounted |
| Helm chart | the `config.json` key of the Secret named in `existingSecret` |
| `.mjs` bundle | the path you pass; without one, `CONTINUUM_LOCAL_CONFIG`, then `./config.json` |

Keys that start with `//` are comments. The Continuum Local panel in Blueprintr
prints the block for each integration, keyed by its ID, ready to paste under
`integrations` (see [Registering an agent](/foliums/blueprintr-user-guide/continuum/local-agent#registering-an-agent)).

## How the agent reads the file

- A value of the wrong type stops the start with a message that gives the key.
  Nothing is guessed: `"true"` in quotes is refused where `true` is meant.
- An unknown key at the top level, inside an integration or inside
  `remoteCredentialScope` is logged as a warning, with the key it probably
  meant, and the agent starts. Inside `discovery`, an unknown key is ignored
  without a warning, except inside `collectors`, where it stops the start.
- `null` counts as not set for top-level, integration and
  `remoteCredentialScope` keys.
- A syntax error is reported by line and column only. The agent never prints
  the text around it, which could be a credential.

```json
{
  "apexUrl": "https://blueprintr.io",
  "displayName": "DC1 agent",
  "enrollmentToken": "env:CONTINUUM_LOCAL_TOKEN",
  "integrations": {
    "<integration ID from the Continuum Local panel>": {
      "provider": "solarwinds",
      "allowedHosts": ["orion.corp.example"],
      "caFile": "/etc/continuum-local/corp-root-ca.pem",
      "credential": {
        "username": "svc-blueprintr",
        "password": "env:SOLARWINDS_PASSWORD"
      }
    }
  }
}
```

## Agent settings

| Key | Type | Default | Meaning and limits |
| --- | --- | --- | --- |
| `apexUrl` | string | required | Your Blueprintr URL, `https://blueprintr.io`. It must be `https://`, with no user name, password, query string or fragment. |
| `displayName` | string | required | Any text that is not empty. Blueprintr shows the name you gave the agent in the Continuum Local panel, not this one. |
| `enrollmentToken` | string or secret reference | none | The single-use token Blueprintr showed when you added the agent. Needed only until the agent has enrolled: remove it afterwards. A different token re-enrols the agent in place. The placeholder from `config.example.json` stops the start. |
| `integrations` | object | `{}` | The integrations this agent serves, keyed by integration ID. See [Integration settings](#integration-settings). An ID that still starts with `REPLACE_WITH`, from the example file, stops the start. |
| `discovery` | object | none | Network sweeps over SNMP. Without it the agent refuses every sweep and SNMP probe. See [Discovery](#discovery). |
| `allowRemoteCredentials` | boolean | `false` | Accept integrations and credentials sent from Blueprintr. Needs `useGateway` on. See [Credentials](/foliums/blueprintr-user-guide/continuum/local-agent#credentials). |
| `remoteCredentialScope` | object | none | Where integrations sent from Blueprintr may connect. See [remoteCredentialScope](#remotecredentialscope). |
| `useGateway` | boolean | `true` | Use the gateway Blueprintr advertises. `false` turns it off, and configuration from Blueprintr with it. |
| `gatewayUrl` | string | none | Pin a gateway instead of the advertised one. Same rules as `apexUrl`. The agent warns at every start when it is not on `apexUrl`'s host or a subdomain of it, because the agent presents its credential there. Ignored while `useGateway` is `false`. |
| `proxy` | string or secret reference | `HTTPS_PROXY`, `https_proxy`, then `HTTP_PROXY` | Proxy for traffic to Blueprintr only: `http://` or `https://`, a host, an optional port and an optional `user:password@`. A path, a query string or another scheme, such as SOCKS, stops the start. |
| `noProxy` | string or list of strings | `NO_PROXY`, then `no_proxy` | Hosts that bypass the proxy, comma-separated or as a JSON list. |
| `extraCaFile` | file path | none | PEM certificates trusted for Blueprintr traffic only, typically a TLS-inspecting proxy's root. |
| `trustSystemCa` | boolean | `true` | Trust the operating system's certificate store as well as the roots built into Node.js, for Blueprintr and for integrations with no `caFile`. |
| `maxConcurrentJobs` | whole number | `4` | Relay and probe jobs run at once, from 1 to 16. At most one sweep runs alongside them. |
| `pollWaitMs` | number | `20000` | Milliseconds a poll asks Blueprintr to wait for work while the gateway WebSocket is not connected. Values outside 1000 to 60000 are clamped to that range, and the agent never asks for more than 25 seconds. |
| `logLevel` | string | `CONTINUUM_LOCAL_LOG_LEVEL`, else `info` | `debug`, `info`, `warn` or `error`, in any letter case. |
| `statePath` | file path | see [Where state is kept](#where-state-is-kept) | The file the enrolled identity is written to. A directory stops the start. |

A value outside what the table allows stops the start, except `pollWaitMs`,
which is clamped. A relative file path resolves against the directory
`config.json` is in.

A file given as `extraCaFile` or `caFile` must contain at least one PEM
certificate. An unreadable file, or one with none, stops the start, and a DER
file is refused with the `openssl` command that converts it. An expired
certificate, or a private key in the same file, is logged as a warning.

## Integration settings

Each entry under `integrations`:

| Key | Type | Default | Meaning and limits |
| --- | --- | --- | --- |
| `provider` | string | required | `solarwinds`, `zabbix`, `prtg`, `checkmk`, `icinga2`, `opmanager`, `whatsupgold`, `netbox`, `infoblox` or `veeam`. It must match the connector the integration uses in Blueprintr, or every request is refused with `unknown_integration`. |
| `allowedHosts` | list of strings | required | The host names or IP addresses this integration may reach, as they appear in its URL in Blueprintr, compared without regard to letter case. At least one. |
| `credential` | object | none | The credential parts the connector needs, by name. Each value is a string or a secret reference. Never sent to Blueprintr. |
| `credentialFile` | file path | none | A JSON object of credential parts, for example written by your secret manager. Its values are used as written, never as secret references. A part set here and in `credential` takes this file's value, with a warning. |
| `caFile` | file path | none | PEM certificates this integration trusts instead of every other root: your internal authority's certificate, or a self-signed appliance's own. |
| `allowInsecureTls` | boolean | `false` | Accept any certificate from this integration's hosts. Logged as a warning at every start. Use `caFile` where you can. |
| `allowPlaintextHttp` | boolean | `false` | Allow `http://` for this integration, which sends the credential unencrypted. Logged as a warning at every start. |
| `allowWriteOperations` | boolean | `false` | Lift the read-only guard for this integration. Logged as a warning at every start. Blueprintr can never set it, and the agent's header checks still apply. See [Read-only by default](/foliums/blueprintr-user-guide/continuum/local-agent#read-only-by-default). |

An `allowedHosts` entry that contains a wildcard, a scheme, a user name, a path
or a port stops the start. Any port on a listed host is allowed. Write IPv4
addresses in plain dotted-decimal form: `010.0.20.5` and `10.1` are refused,
because resolvers read them differently. IPv6 addresses may be written with or
without brackets.

| Provider | Credential parts |
| --- | --- |
| `solarwinds`, `checkmk`, `icinga2`, `whatsupgold`, `infoblox`, `veeam` | `username`, `password` |
| `zabbix`, `prtg`, `opmanager`, `netbox` | `token` |

A part the connector needs but cannot find fails the request with
`credential_missing`, and the message gives the part's name.

## remoteCredentialScope

This block limits integrations sent from Blueprintr, and has no effect while
`allowRemoteCredentials` is off. A host in such an integration must match at
least one entry.

| Key | Type | Meaning and limits |
| --- | --- | --- |
| `hosts` | list of strings | Host names allowed exactly, with the same rules as `allowedHosts`. |
| `domainSuffixes` | list of strings | Domains whose hosts are allowed, such as `monitoring.corp.example`, written without a leading dot or wildcard. A single label is refused unless it is private by convention: `internal`, `local`, `localdomain`, `lan`, `corp`, `home`, `intranet`, `private` or `test`. An IP address is refused: put it in `cidrs`. |
| `cidrs` | list of strings | IPv4 or IPv6 ranges. They cover hosts written as IP addresses and the addresses a host name resolves to, checked again at every connection. A range with bits set below its prefix is refused with the corrected range, and `/0` is refused. A range broader than /8 for IPv4 or /16 for IPv6 is logged as a warning at every start. |
| `allowTlsOverrides` | boolean, default `false` | Let Blueprintr set `allowInsecureTls` or `caFile` on an integration it sends. Logged as a warning at every start when on. |

With or without a scope, loopback, link-local (including the cloud metadata
address 169.254.169.254) and unspecified addresses, and `localhost` names, are
refused for integrations sent from Blueprintr unless a `cidrs` entry covers
them. With `allowRemoteCredentials` on and no scope, the agent warns at every
start that such an integration may reach any host that is not loopback or
link-local. A scope with no entries refuses every one.

## Discovery

| Key | Type | Default | Meaning and limits |
| --- | --- | --- | --- |
| `cidrs` | list of IPv4 ranges | none | The ranges a sweep may cover. A bare address is a /32. A range larger than `maxSweepPrefix` allows stops the start. With none, the agent refuses every sweep. |
| `exclude` | list of IPv4 addresses or ranges | `[]` | Never probed by a sweep. |
| `credentialSets` | list | required | At least one. See [Credential sets](#credential-sets). |
| `credentialTrial` | `"parallel"` or `"sequential"` | `"parallel"` | `parallel` tries every set that applies to a host at once: a dead address costs one timeout, and every applicable community reaches every host. `sequential` tries them one at a time in the order written and stops at the first that answers: fewer communities reach each host, and a dead address costs one timeout per set. |
| `collectors` | object | every collector planned for the device's class | `{ "allow": [...] }` runs only the named collectors, `{ "deny": [...] }` runs all but them, and both together mean allow minus deny. Names: `interfaces`, `addresses`, `entity`, `lldp`, `cdp`, `bridge`, `vlans`, `fdb`, `arp`, `routes`, `health`, `hostResources`, `vmware`, `printer`, `ups`. |
| `collectContact` | boolean | `true` | `false` never requests `sysContact`, which often identifies a person. |
| `concurrency` | number | `16` | Devices profiled at once, 1 to 256. |
| `packetsPerSecond` | number | `50` | SNMP packets a second, 1 to 5000, shared by every sweep and probe the agent runs. |
| `timeoutMs` | number | `1500` | Milliseconds per request, 100 to 30000. |
| `retries` | number | `1` | Retries per request, 0 to 5. |
| `maxSweepPrefix` | number | `22` | The largest range allowed in `cidrs`, as a prefix length, 16 to 32. |
| `maxHosts` | number | `65534` | Addresses probed in one sweep, 1 to 65534. Addresses past it are skipped. |
| `deviceBudgetMs` | number | `60000` | Milliseconds per device, every collector included, 5000 to 600000. |
| `port` | number | `161` | The SNMP port, 1 to 65535. |
| `maxRowsPerTable` | number | `20000` | Rows read from one table on one device, 100 to 200000. |
| `maxVlanWalks` | number | `64` | VLANs walked one by one on switches that keep their bridge tables per VLAN, 0 to 4094. |

A number outside its range, or a collector name that does not exist, stops the
start. Denying `arp` or `fdb`, or setting `collectContact` to `false`, also
limits what Blueprintr can request from a device directly: raw requests then
return only the objects the permitted collectors read.

A sweep probes only addresses inside `cidrs` and outside `exclude`. An SNMP
probe of one device may also reach a host in its integration's `allowedHosts`,
whatever `cidrs` and `exclude` say, on the port the probe gives, with the
credential sets that apply to that host. A set without its own `cidrs` applies
to every host, host names included.

### Credential sets

| Key | Meaning and limits |
| --- | --- |
| `name` | Required, and different for each set. |
| `version` | `"1"`, `"2c"` or `"3"`. Default `"2c"`. |
| `community` | Required for versions 1 and 2c. May be a secret reference. |
| `user` | Required for version 3. |
| `securityLevel` | `noAuthNoPriv`, `authNoPriv` or `authPriv`. Left out, it follows the passphrases given: `authPriv` with a `privPassphrase`, `authNoPriv` with only an `authPassphrase`, otherwise `noAuthNoPriv`. |
| `authProtocol` | `md5`, `sha`, `sha224`, `sha256`, `sha384` or `sha512`. Required for `authNoPriv` and `authPriv`. |
| `authPassphrase` | At least 8 characters. Required for `authNoPriv` and `authPriv`. May be a secret reference. |
| `privProtocol` | `des`, `aes128`, `aes192` or `aes256`, or `aes192b` and `aes256b` for devices that use the Blumenthal key extension. Required for `authPriv`. |
| `privPassphrase` | At least 8 characters. Required for `authPriv`. May be a secret reference. |
| `contextName` | Optional SNMPv3 context. |
| `cidrs` | IPv4 ranges, each inside `discovery.cidrs`. The set is tried only against addresses inside them. An empty list, or a range outside `discovery.cidrs`, stops the start. |

## Secret references

A credential part, an SNMP community or passphrase, `enrollmentToken` and
`proxy` can each be written as a reference instead of the value.

| Written as | Means |
| --- | --- |
| `"env:NAME"` | The value of environment variable `NAME`. A variable that is unset or empty stops the start. |
| `"file:/absolute/path"` | The file's contents, with one trailing newline removed. The path must be absolute, and the file a regular, non-empty file of at most 64 KiB. |
| `"literal:..."` | The text after `literal:`, for a value that starts with `env:` or `file:`. |

References are resolved once, at start, so rotating a secret takes a restart.
A reference that cannot be resolved stops the start with a message that says
where it sat, never the value. Values in a `credentialFile` are never treated
as references.

Set the variables where the service reads them: `/etc/continuum-local/environment`
for the Linux packages, the container's environment, or `extraEnv` for the
Helm chart. On Windows, use `file:` references: environment variables added to
the service are replaced by every upgrade.

## Environment variables

| Variable | Meaning |
| --- | --- |
| `CONTINUUM_LOCAL_CONFIG` | The config path when none is given on the command line. The container sets it to `/etc/continuum-local/config.json`. |
| `CONTINUUM_LOCAL_STATE_DIR` | The state directory when the config has no `statePath`. The systemd unit, the Windows service, the container and the Helm chart set it. |
| `CONTINUUM_LOCAL_LOG_LEVEL` | The log level when the config has no `logLevel`. A value that is not a level means `info`. |
| `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY` | The proxy for Blueprintr traffic when the config sets none, read in that order. |
| `NO_PROXY`, `no_proxy` | Hosts that bypass the proxy when the config sets no `noProxy`. |
| `NODE_EXTRA_CA_CERTS` | Extra roots, read by Node.js at start and trusted for every connection, your on-premise systems included, except an integration with its own `caFile`. For a proxy's root, use `extraCaFile`. |

## Where state is kept

The state directory contains the agent's enrolled identity,
`agent-state.json`, and with `allowRemoteCredentials`, one file per
integration sent from Blueprintr under `remote-integrations`. The agent creates
the directory with mode 0700 and each file with mode 0600, and checks that it
can write there before it spends an enrolment token.

Without a `statePath`, the agent uses the first of these that applies:

1. `CONTINUUM_LOCAL_STATE_DIR`.
2. `STATE_DIRECTORY`, which systemd sets for the unit.
3. On Windows, `%ProgramData%\Continuum Local\state`.
4. On Linux, `/var/lib/continuum-local`, when the config is
   `/etc/continuum-local/config.json`.
5. The directory `config.json` is in.

## File permissions

- `config.json` can contain credentials. On the Linux packages it is owned by
  `root`, group `continuum-local`, with mode 0640, and every install or upgrade
  sets it back to that. Keep it that way: the service runs as
  `continuum-local`, so it cannot read a root-owned file with mode 0600. Mode
  0600 suits a file owned by the account the agent runs as, such as the `.mjs`
  bundle under a service account. The agent warns at every start when the file
  is readable by every user, or writable by anyone but its owner, and checks
  each `credentialFile` the same way.
- On Windows the agent skips that check. The installer restricts
  `C:\ProgramData\Continuum Local` so the service can read `config.json` but
  not change it, and can write only to `state` and `logs`.
- `/etc/continuum-local/environment` is owned by `root` with mode 0600.
  systemd reads it as root, so the service account never needs to.
- `continuum-local check` warns when the state file is readable by other
  users.

## What Blueprintr receives from this file

On every poll, the agent reports its version, protocol version, platform and
capabilities, including whether it accepts configuration from Blueprintr, the
IDs of its integrations and the ranges in `discovery.cidrs`. At enrolment it
also sends `displayName`, which Blueprintr does not keep. Blueprintr uses the
report to send the agent only work it can do and to offer its ranges when you
start a sweep. Host names, credentials, certificates and every other setting
stay on the agent.

Blueprintr keeps the latest report on the agent's record until the agent is
deleted. People who can manage Continuum integrations for the organisation or
team can see all of it, and Blueprintr staff who run the service see the
version, platform, protocol version and capabilities.

## Logging

The agent writes one JSON object per line, with `ts`, `level` and `message`
and any other fields: `info` and `debug` to standard output, `warn` and
`error` to standard error. Before a line is written, each credential value the
agent loaded is masked in its plain, JSON-escaped and URL-encoded forms. A
value shorter than four characters is not masked.

`logLevel` sets which lines are written. Security warnings are written at
every level. They cover write operations permitted, certificate checking off,
`http://` allowed, configuration from Blueprintr with no scope or with TLS
overrides allowed, a very broad scope range, a pinned gateway off your
Blueprintr domain, a config or credential file others can read or change, a
certificate file that also contains a private key, and each integration sent
from Blueprintr that uses a TLS override.

Where each install writes its log is in
[Troubleshooting](/foliums/blueprintr-user-guide/continuum/local-agent/troubleshooting#logs).

## The check command

```
continuum-local check [config.json] [--port N | --port ID=N]... [--timeout MS]
```

`check` tests the path the agent will take and prints what to change when
something fails. It reads the config from the argument, else
`CONTINUUM_LOCAL_CONFIG`, else `./config.json`. It prints no secret and sends
nothing beyond TLS handshakes, so it cannot enrol, spend a token or claim
work.

| Section | What it tests |
| --- | --- |
| Configuration | The file loads, with a summary: integrations, discovery on or off, configuration from Blueprintr on or off, and jobs at once. Every warning and notice the agent would log at start follows. |
| State | The state directory is writable, and the agent is enrolled or has an `enrollmentToken`. |
| Trust | The certificate roots in use: Node.js's defaults, `NODE_EXTRA_CA_CERTS`, the system store, `extraCaFile` and each integration's `caFile`. |
| Blueprintr | The proxy in use, then DNS, TCP and a verified TLS handshake with Blueprintr, and with the gateway when one is known. |
| Integrations | DNS and a verified TLS handshake, direct and never through the proxy, with every host in every `allowedHosts`, eight at a time. |

Each line starts with `ok`, `WARN`, `FAIL` or `--` for information, and the
report ends with a `Result:` line. `check` exits with 0 when everything
required passed and 1 otherwise. The gateway is not required: an agent that
cannot reach it polls.

| Option | Meaning |
| --- | --- |
| `--port N` | The port to try on every integration host. Default 443. |
| `--port ID=N` | The port for one integration, by ID, such as `--port <ID>=17774` for SolarWinds Orion. Repeat it for others. |
| `--timeout MS` | Milliseconds allowed for each connection attempt, 100 to 120000. Default 10000. |

On the Linux packages, run `sudo continuum-local check /etc/continuum-local/config.json`.
Run as root, the command reads `/etc/continuum-local/environment` the way
systemd does, then runs as the `continuum-local` user, so it sees the same
proxy, certificate roots and file permissions as the service.

`continuum-local --version` prints the agent version, the protocol version,
the Node.js version and the platform.

---

# Blueprintr User Guide: Security model
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/security

> What the agent enforces, what Blueprintr stores and for how long, where credentials are kept, and how releases are signed.

Continuum Local runs connector requests and SNMP sweeps inside your network for
Blueprintr. Blueprintr decides what to ask for. The agent decides what it will
do, by a policy that only its configuration file sets, and treats every job from
Blueprintr as untrusted input.

## Trust boundaries

| Party | Runs where | Decides |
| --- | --- | --- |
| Your configuration file | The agent's host | Which systems the agent serves, the hosts each may reach, the address ranges it may sweep, and the credentials it uses |
| The agent | A host, container or pod you run | Whether each job fits that policy, before a socket opens |
| Blueprintr | Blueprintr's servers | Which requests to propose, and what to do with the answers |

The agent dials out and listens on no port. Every exchange starts on your side:
it asks Blueprintr for work, runs it locally and posts the result back. The deb,
rpm and MSI installs let the agent's own account read `config.json` but not
change it, so a compromised agent process cannot rewrite its own configuration.

## What Blueprintr stores

| Data | What it contains | Why | Who can see it | How long |
| --- | --- | --- | --- | --- |
| Agent record | The name you gave it, its version, platform, protocol version and capabilities, the integration IDs it serves, its discovery ranges and when it was last seen. A keyed hash of its secret, never the secret | To send each job to an agent that can run it, and to show its status | People who can manage Continuum integrations on the organisation or team that owns it. Blueprintr staff who run the service see its name, owner, status, version, platform and capabilities | Until you delete the agent. Revoking keeps the record |
| Enrolment token | A hash of the token | To enrol the agent once | Nobody. The token is shown once, when it is created | Deleted 30 days after it is used or expires |
| Relay job | The request Blueprintr asked the agent to make, with placeholders where credentials go, and the answer the agent returned | To pass the answer to the connector that asked for it | Blueprintr's servers only. Staff see counts of outcomes, not contents | The job expires two minutes after it is created, and is deleted at the agent's next poll after that or by Blueprintr's scheduled clean-up |
| Saved panel | The fields the connector takes from that answer, saved as the tab's snapshot | To show it on the stratum | Everyone who can read the blueprint, including anonymous readers, embeds and exports on a public blueprint. NetBox panels are for Blueprint editors unless you choose all Blueprint readers, and Infoblox and Veeam Backup & Replication panels are for Blueprint editors only. The [connector reference](/foliums/blueprintr-user-guide/continuum/connector-reference) lists what each panel shows | Until an editor refreshes or removes the tab. Unlinking cannot recall copies already in versions, exports or embeds |
| Sweep results | The devices, ports and links each [network sweep](/foliums/blueprintr-user-guide/continuum/local-agent/network-discovery) finds, and the MAC and IP addresses those devices have learned. Never a device's contact field, or which SNMP credential or version answered | To show your estate on the sweep results page | People who can manage Continuum integrations on the owning organisation or team. Staff see counts only | 90 days from when a sweep starts. The latest complete sweep from each agent is kept until a newer one completes. Deleting an agent deletes its sweeps |
| Audit log entries | Agent created, enrolled, renamed, revoked and deleted, tokens issued, sweeps and schedules, and credentials sent or removed: who, with a hash of their IP address and their browser's user agent, which agent, which integration, and the outcome. Never a credential | Accountability | People who can read the organisation's audit log, and the team's for a team's agent | With the rest of the audit log, which does not expire automatically |
| Download record | Which file and version you downloaded from the download page, and when, with a hash of your IP address and your browser's user agent | To answer who downloaded which build, for example after an incident | Blueprintr staff who run the service. It is recorded against your account, not the organisation, so it is not in the organisation's audit log | With the rest of the audit log, which does not expire automatically |

Deleted rows stay in Blueprintr's database backups for up to 7 days.

## Where credentials are kept

Blueprintr never stores a credential for an on-premise system.

| Credential | Where it is kept |
| --- | --- |
| Monitoring system credentials you configure | `config.json`, or an environment variable or file it refers to (`env:NAME`, `file:/path`), or a `credentialFile` your secret manager writes |
| SNMP communities and SNMPv3 passphrases | The `discovery` block of `config.json`, or the variables and files it refers to |
| Credentials sent from Blueprintr | The agent's state directory, one file per integration, mode 0600 |
| The agent's own identity for Blueprintr | The agent's state directory, mode 0600 |
| Access tokens minted by WhatsUp Gold and Veeam Backup & Replication | The agent's memory only |

The agent does not encrypt these files itself. They are protected by file
permissions, so use disk encryption on the host if your policy requires
encryption at rest.

For a credential in the agent's configuration, Blueprintr never receives the
value. Its request has an unguessable placeholder where the credential goes.
The agent fills in the local value and refuses to send the request if any
placeholder is left in it. When an answer repeats a credential the agent sent,
or a token it kept, the agent replaces it with `[redacted]` before the answer
leaves, in plain, JSON, percent-encoded and form-encoded spellings. Values
shorter than six characters are not scrubbed.

### Credentials sent from Blueprintr

This is off unless the agent's configuration sets
`"allowRemoteCredentials": true`. When it is on, a credential typed into
**send credentials** takes this path:

1. From your browser to Blueprintr's web application, over HTTPS.
2. From the web application to Blueprintr's agent gateway, as an encrypted,
   single-use message.
3. From the gateway to the agent, over the agent's open connection to
   `agents.blueprintr.io`.
4. The agent checks it against its own limits and writes it to its state
   directory.

Nothing on that path writes the credential to a database, a queue or a log.
There is nowhere to keep it in the meantime, so the agent has to be online and
connected to the gateway at the time, or the send fails and nothing is queued.
Where Blueprintr does not offer the gateway, every send is refused as not set
up.

The agent applies limits that only its configuration can set:

- `remoteCredentialScope` lists the hosts, domain suffixes and address ranges
  Blueprintr may configure. Addresses are checked again at every connection,
  against the address the name resolves to at that moment.
- Loopback, link-local (including `169.254.169.254`), unspecified addresses and
  `localhost` names are refused unless a `cidrs` entry in that scope covers them.
- Certificate settings sent from Blueprintr are refused unless the scope sets
  `allowTlsOverrides`. `allowWriteOperations` is never accepted from Blueprintr.
- An integration in `config.json` always wins. Blueprintr can neither replace
  nor remove it.
- Credentials sent to an agent are deleted if it is enrolled again as a
  different agent.

## What the agent enforces

Every job is checked before a socket opens:

- A relay or probe must be for an integration in the agent's configuration, or
  one sent from Blueprintr, and a relay's provider must match that entry's.
- A relay's host must be in that integration's `allowedHosts`, written exactly,
  with no wildcards, ports or paths. The check runs again after the credential
  is filled in, and on each of up to three redirects. A redirect to another host
  drops credential headers, and a request with a credential in its URL or body
  is not followed to another host.
- An answer larger than the request allows (8 MB at most) is refused. So is a
  result larger than one poll to Blueprintr can carry, which is about 1 MB of
  answer. Both are reported as `response_too_large`. A relay runs for 10
  minutes at most.
- A sweep reaches only addresses inside `discovery.cidrs` and outside
  `exclude`. An SNMP probe of one device reaches only an address a sweep may
  reach or a host in the integration's `allowedHosts`, and a TCP connection
  test only a host in `allowedHosts`. An agent with no `discovery` block sends
  no SNMP at all.
- Whatever `allowWriteOperations` says, a request that sets `Host`,
  `Transfer-Encoding`, `Connection`, `Keep-Alive`, `Upgrade`, `TE`, `Trailer`,
  `Expect`, `Proxy-Connection` or `HTTP2-Settings`, or sets one header twice in
  different letter case, is refused. The agent writes `Content-Length` itself.
- `Set-Cookie` and `Set-Cookie2` headers are removed from every answer, and
  Blueprintr removes them again before storing a result.

### The read-only guard

The allow-list decides where the agent may connect. The read-only guard decides
what a request may do there: the agent relays only requests that read, checked
for each provider on method, path and, where the product needs it, the query or
body. For NetBox, Infoblox, Veeam Backup & Replication and PRTG it accepts only
the exact endpoints the connector uses. For SolarWinds, Zabbix, Checkmk,
Icinga 2, ManageEngine OpManager and WhatsUp Gold it accepts any read that
product's API offers, so give the agent an account that can read only what
Blueprintr should see. The rules come from the provider in your configuration,
never from the job. Anything else is refused with `operation_not_allowed`.

Some reads are refused too, because their answers would contain a stored
secret: PRTG's `getobjectproperty.htm` and `getpasshash.htm`, OpManager
operations that name keys, passwords or credentials, NetBox's token and config
context endpoints, and Infoblox's credential fields. The guard also refuses a
method-override header asking for anything but `GET`, and a path with encoded
slashes, backslashes, encoded dots, path parameters or empty segments.

Setting `"allowWriteOperations": true` on one integration in `config.json` lifts
the guard for that integration only. The agent logs a warning about it at every
start.

### The token vault

WhatsUp Gold and Veeam Backup & Replication exchange a username and password for
an access token. The agent replaces `access_token` and `refresh_token` in that
answer with a handle (`BPLV_` and 32 hex characters), keeps the token in memory,
and puts it back when the handle appears in a later request for the same
integration.

- A handle works only for the integration it was issued for.
- Tokens are never written to disk. Each expires with the token, after a day at
  most, and all are lost on restart, after which the connector asks for a new
  one.
- Blueprintr can ask for more fields to be kept back, never fewer.
- An answer the agent cannot fully check for a token is refused with
  `credential_unresolved`. A refresh grant is refused.

## Certificate checking

| Connection | Trusted roots | Turning checks off |
| --- | --- | --- |
| To Blueprintr | Node.js's bundled roots, the operating system's store (`trustSystemCa`, on by default), `NODE_EXTRA_CA_CERTS` and `extraCaFile`. `apexUrl` must be `https://` | The agent has no setting for it |
| To your systems | The same, except `extraCaFile`. An integration with a `caFile` trusts that file alone | `allowInsecureTls` or `allowPlaintextHttp` on one integration, each logged as a warning at every start |

The agent adopts a gateway that Blueprintr advertises only when it is
`https://` on your `apexUrl`'s host or a subdomain of it. The proxy is used for
traffic to Blueprintr only, never for connections to your systems, as
[Proxies](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements#proxies)
describes.

## Service hardening

| Install | Runs as | Restrictions |
| --- | --- | --- |
| deb, rpm | `continuum-local`, a system account with no login shell | `config.json` is `root:continuum-local`, mode 0640, in a 0750 directory. The systemd unit sets no new privileges, an empty capability set, a read-only filesystem apart from `/var/lib/continuum-local` (0700), no access to home directories, a private `/tmp` and devices, protected kernel settings, IPv4, IPv6 and Unix sockets only, restricted namespaces and a 512 MB memory ceiling. Write-execute memory stays allowed, because the JavaScript engine's compiler needs it |
| Windows MSI | `NT AUTHORITY\LocalService` | `C:\ProgramData\Continuum Local` has its own access list with no inherited entries: SYSTEM and Administrators have full control, and the service may read `config.json` but not change it, and write only to `state` and `logs`. A first install leaves the service stopped and set to Manual |
| Container | The unprivileged `node` user (uid 1000) | The state directory is 0700. npm, npx, corepack and yarn are removed from the image |
| Helm chart | uid 1000, non-root | Read-only root filesystem, every capability dropped, no privilege escalation, the runtime's default seccomp profile, one replica, and no Service or Ingress |

Logs mask every credential and secret reference value the agent loaded, and
anything shaped like a placeholder. The agent writes a warning at every start,
whatever the log level, for each setting that widens what it may do: write
operations, certificate checks off, `http://`, credentials from Blueprintr with
no scope or with certificate overrides, a gateway off your Blueprintr domain, a
configuration or credential file others can read, and a CA file that contains a
private key.

## Supply chain

- The agent has no runtime dependencies. Its SNMP stack, including SNMPv3
  security and DES, is part of the agent, and the bundle is one unminified
  JavaScript file your team can read.
- The deb, rpm and MSI include Node.js 24. The build refuses a Node.js archive
  whose SHA-256 is not pinned in the agent's repository, and the pinned values
  were checked against the Node.js project's signed checksum list. The Windows
  service wrapper, WinSW, is pinned by checksum as well. The container image
  starts from the official Node.js 24 Alpine image, pinned by digest.
- Every release is signed with Sigstore keyless signing by the agent's release
  workflow, and recorded in Sigstore's public transparency log. Accept a
  signature only from that workflow at the version's tag, with the
  [verification commands](/foliums/blueprintr-user-guide/continuum/local-agent/releases#verify-the-downloads).
  `SHA256SUMS` covers the downloads, and the container image and chart are
  signed by digest.
- From 0.2.0, each release also includes a CycloneDX SBOM bound to the bundle by
  a signed attestation, and the container image's package list and
  vulnerability scan. A release is not published if that scan finds a critical
  vulnerability with a fix available.

## If Blueprintr were compromised

An attacker in control of Blueprintr could:

- make the reads each connector's rules allow, to the hosts you listed, with
  your credentials, and see the answers without the credentials, tokens or
  cookies in them. A least-privilege, read-only account limits what those
  answers contain;
- start sweeps inside your discovery ranges, and SNMP probes there or on hosts
  you listed, on a UDP port it chooses, with your SNMP credentials, and see the
  results within the collectors you allow;
- test TCP connections to hosts in an integration's `allowedHosts`;
- with `allowRemoteCredentials` on, read credentials typed into Blueprintr as
  they pass through, and configure integrations for any host your scope allows.
  With no `remoteCredentialScope`, that is any host except loopback, link-local
  and unspecified addresses;
- with `allowWriteOperations` on an integration, send writes to its hosts;
- stop sending work, or show you wrong results.

It could not:

- reach a host outside `allowedHosts`, `discovery.cidrs` or your scope;
- see the credentials in `config.json`: Blueprintr's requests have
  placeholders, and the agent scrubs the values it inserted from each answer, in
  the spellings listed above;
- see an SNMP community or passphrase, which never appears in a result, or a
  token the vault keeps;
- send a write where `allowWriteOperations` is off, turn it on, or send
  certificate settings without `allowTlsOverrides`;
- change `config.json`, or replace or remove an integration defined there;
- widen a sweep, or read ARP, forwarding or contact data through a raw probe
  when you have turned those collectors off;
- connect to the agent, redirect its connection to a host outside your
  `apexUrl`'s domain, upgrade it, or give it code to run. Every job is one of a
  fixed set of request types.

## Reporting a vulnerability

Email **support@blueprintr.io** with "Security: Continuum Local" in the subject.
Include the agent version (`continuum-local --version`), how it is installed,
what you found, how to reproduce it and what an attacker gains. Remove
credentials, host names and customer data from any proof of concept, and never
send a `config.json` or state file: both contain live credentials.

Blueprintr aims to acknowledge a report within 3 working days and to give its
assessment within 10, agrees a disclosure date with you, and credits you in the
release notes if you want. Test only against an agent and a Blueprintr account
that are yours. Fixes ship as a new release, and only the latest release is
supported before version 1.0.

---

# Blueprintr User Guide: Network discovery
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/network-discovery

> What an SNMP sweep reads, the discovery policy that limits it, and how to start, schedule and review sweeps.

A network sweep asks an agent to find the SNMP devices in address ranges you
allow, profile each one, and upload what it finds to Blueprintr. The agent
sweeps only the ranges in the `discovery` block of its own configuration.
Blueprintr can narrow a sweep to some of them but never widen it, and the SNMP
credentials stay on the agent. An agent with no `discovery` block sends no SNMP
at all.

## The discovery policy

```json
"discovery": {
  "cidrs": ["10.0.10.0/24", "10.0.20.0/23"],
  "exclude": ["10.0.10.250"],
  "credentialSets": [
    { "name": "netops", "version": "3", "user": "netops", "securityLevel": "authPriv",
      "authProtocol": "sha256", "authPassphrase": "env:SNMP_NETOPS_AUTH",
      "privProtocol": "aes128", "privPassphrase": "env:SNMP_NETOPS_PRIV" },
    { "name": "dc", "version": "2c", "community": "file:/etc/continuum-local/dc-community",
      "cidrs": ["10.0.20.0/24"] }
  ],
  "credentialTrial": "sequential",
  "collectors": { "deny": ["arp", "fdb"] },
  "collectContact": false,
  "packetsPerSecond": 50
}
```

| Setting | Default | What it limits |
| --- | --- | --- |
| `cidrs` | none (no sweeps without it) | The addresses a sweep may probe. IPv4 only, in plain dotted-decimal: `010.0.20.5` and similar spellings are refused |
| `exclude` | none | Addresses or blocks a sweep never probes |
| `maxSweepPrefix` | `22` | The largest block allowed in `cidrs`, as a prefix length. It can never be set below 16 |
| `maxHosts` | `65534` | Addresses in one sweep |
| `packetsPerSecond` | `50` | SNMP packets a second, shared by every sweep and probe the agent runs. 1 to 5000 |
| `concurrency` | `16` | Devices profiled at once. 1 to 256 |
| `timeoutMs`, `retries` | `1500`, `1` | Per request |
| `deviceBudgetMs` | `60000` | Time allowed per device, every collector included |
| `port` | `161` | The SNMP port |
| `maxRowsPerTable`, `maxVlanWalks` | `20000`, `64` | Rows read from one table on one device, and VLANs walked one by one on switches that keep a forwarding table per VLAN |

An SNMP probe of one device is the exception to `cidrs` and `exclude`: it may
also reach a host in its integration's `allowedHosts`, on the port the probe
gives, and tries each credential set that applies to that host. A set without
its own `cidrs` applies to every host, host names included.

## SNMP credentials

Use SNMPv3 with `authPriv` wherever your devices support it. SNMPv1 and v2c
send the community string in clear text in every request, so anything on the
path, and any device the sweep reaches, can read it. SNMPv3 `authPriv`
authenticates and encrypts each request.

| Version | Needs |
| --- | --- |
| `"1"`, `"2c"` | `community` |
| `"3"` | `user` and `securityLevel` (`noAuthNoPriv`, `authNoPriv` or `authPriv`), then as the level requires `authProtocol` (`md5`, `sha`, `sha224`, `sha256`, `sha384`, `sha512`) with `authPassphrase`, and `privProtocol` (`des`, `aes128`, `aes192`, `aes256`, or `aes192b` and `aes256b` for devices using the Blumenthal key extension) with `privPassphrase`. Optional `contextName` |

Passphrases must be at least 8 characters. Any community or passphrase can be an
`env:NAME` or `file:/path` reference instead of the value.

Give each credential set the ranges it belongs to with its own `cidrs`, each
inside `discovery.cidrs`. A set with `cidrs` is only tried against those
addresses.

`credentialTrial` sets how the sets that apply to an address are tried:

- `"parallel"` (the default) sends every applicable set at once. A dead address
  costs one timeout, but every applicable community reaches every address.
- `"sequential"` tries them one at a time, in the order written, and stops at
  the first that answers. Communities are not sprayed, and a dead address costs
  one timeout per set.

Communities and passphrases never appear in a request from Blueprintr or in a
result, and are masked in the agent's logs. Blueprintr does not keep which
credential set or SNMP version a device answered.

## What your network sees

- UDP from the agent's host to port 161 (or `port`) on addresses in the ranges:
  SNMP GET, GETNEXT and GETBULK requests. A probe of one device may also send
  them to a host in its integration's `allowedHosts`, on the port the probe
  gives. SNMPv3 opens each device with the standard engine discovery request,
  which has an empty user name.
- At most `packetsPerSecond` packets a second across everything the agent sends
  over SNMP.
- The agent does not send ICMP, scan ports or open raw sockets, and needs no
  root access.
- On older Cisco IOS switches, walks of the per-VLAN forwarding table use
  `community@vlan`, or with SNMPv3 the `vlan-N` context, which the switch must
  permit for that user.

A device that logs or traps SNMP authentication failures does so for each
credential set that does not match it. Tell whoever watches your intrusion
detection before the first sweep, and add the agent's address to any device
that limits SNMP to named managers.

## What a sweep collects

Each responding device is classified before any table is walked: `sysObjectID`
gives the vendor, `sysDescr` the operating system, version and model, and one
request for a dozen objects shows whether it bridges, routes, prints, runs on
batteries or is a general-purpose host. The class picks which collectors run,
so a core switch is walked for neighbours, VLANs and forwarding tables while a
printer is asked for its supplies. Every device is also asked for its system
group: name, description, uptime, location and, unless `collectContact` is
`false`, contact.

| Collector | Reads |
| --- | --- |
| `interfaces` | Name, description, type, speed, MTU, MAC address, state, and traffic, error and discard counters |
| `addresses` | The device's own IP addresses and masks |
| `entity` | Model, serial number, hardware, firmware and software revisions, and stack members |
| `lldp`, `cdp` | Neighbours, from LLDP and from Cisco's CDP |
| `bridge` | Which bridge port is which interface |
| `vlans` | VLANs and the ports in each |
| `fdb` | The forwarding table: which MAC address is behind which switch port |
| `arp` | The ARP table: the MAC address behind each IP address |
| `routes` | The routing table, up to 5,000 routes |
| `health` | CPU, memory, temperature, load and sessions, where the device reports them |
| `hostResources` | Storage, memory, processor load, users and processes on servers |
| `vmware` | The ESXi version, and each virtual machine's name, guest OS, memory, power state and CPUs |
| `printer` | Supplies and their levels |
| `ups` | Battery state |

Choose collectors with `"collectors": { "allow": [...] }` or
`{ "deny": [...] }`. A name that is not a collector stops the agent at start.

### Personal data

The ARP table (which address each laptop and phone has), the forwarding table
(which switch port each device is behind) and the contact field identify people
rather than network equipment. If your data protection review rules them out,
deny `arp` and `fdb`, and set `"collectContact": false`, which stops the agent
asking for the contact field at all.

With any of those off, an SNMP probe Blueprintr sends for named objects or a
subtree returns only the objects the permitted collectors read. The IPv6
neighbour cache and vendor tables with the same kind of data are withheld too,
and a request that could return nothing else is refused before a packet is
sent. Denying `bridge` or `vlans` leaves forwarding table rows without port and
VLAN names.

Blueprintr drops a device's contact field before storing a sweep, whatever
these settings say.

## Running a sweep

Sweeps are in **Network sweeps**, below the Continuum Local panel in
**Settings → Continuum** on the organisation or team. You need
`continuum_integrations.manage` there, and the organisation that owns the agent
needs an Enterprise plan.

> [!STEPS]
>
> === Choose an agent
>
> Only agents that are online, report discovery ranges and are not already
> sweeping are offered. The others are listed with the reason. An agent reports
> its ranges from version 0.2.0.
>
> === Choose ranges
>
> Pick from the ranges the agent reported, or type smaller ones inside them.
> Choosing none sweeps all of them.
>
> === Set limits
>
> **Time limit** is the agent's default (one hour), or 15 minutes to 4 hours.
> **Stop after (hosts, optional)** sweeps only the first that many addresses in
> the ranges.
>
> === Start sweep
>
> The run appears under **Recent sweeps** as **Waiting for the agent**, then
> **Running**.

An agent runs one sweep at a time, for 5.5 hours at most. It uploads results as
it finds them and reports progress every five minutes, and a run that hears
nothing from its agent for 20 minutes is marked **Agent stopped reporting**. A
sweep that runs out of time, or whose agent stops, keeps everything uploaded
before then.

To stop one, choose **Cancel**, then **Stop it**. Everything already uploaded is
kept. The agent is told at its next upload and stops probing there.

### Schedules

Under **Schedules**, choose **Add a schedule**, then the agent, **How often**
(**Every day** or **Every week**), **First run (your time)**, **Time limit** and
the ranges, and **Save schedule**. **Pause** and **Resume** stop and restart a
schedule. A scheduled sweep that comes round while its agent is offline or
already sweeping is skipped, and the next one runs as normal. Missed sweeps are
not run later.

## Reading the results

**Watch** opens a running sweep, whose page updates every few seconds, and
**View results** opens a finished one. The page shows who started it, or that a
schedule did, the ranges and any warnings, then two sections:

| Section | Shows |
| --- | --- |
| **Devices** | Name, class, vendor, model, management address, version, interfaces up and down, and addresses learned. Search by name, address, vendor or model, and select a name to open the device. A switch opens as a front panel of its ports and the addresses learned on each. |
| **Links** | Connections between two devices the sweep reached, from LLDP and CDP, with the port at each end. Links arrive at the end of a sweep. Neighbours outside the ranges, such as phones and access points, are counted but not listed. |

The page never shows which SNMP credential or version a device answered.
Nothing puts sweep results on a diagram or a stratum: they appear only on these
pages.

A sweep that finds no devices usually means the credentials in the agent's
`discovery` block do not match the devices, or a firewall blocks UDP port 161
between the agent and them.

## What Blueprintr keeps

| Question | Answer |
| --- | --- |
| What | The devices, ports and links each sweep finds, and the MAC and IP addresses those devices have learned. Never a device's contact field or anything about the SNMP credentials |
| Why | To show your estate on the results page |
| Who can see it | People who can manage Continuum integrations for the organisation or team. Blueprintr staff see only how many sweeps ran |
| How long | 90 days from when a sweep starts, except that the latest complete sweep from each agent is kept until a newer one completes. Deleting an agent deletes its sweeps |

## Testing on one host first

On the agent's host, `continuum-local probe` profiles one device and prints its
class and the collectors it would run, and `continuum-local discover` sweeps
the policy's ranges and prints a report without sending anything to Blueprintr.
On the Linux packages, run them with `sudo`: they then run as the
`continuum-local` account, with the service's environment file.

---

# Blueprintr User Guide: Releases and verification
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/releases

> How Continuum Local releases are versioned and signed, what each one contains, how to verify a download or image, and which agent versions Blueprintr supports.

Every Continuum Local release is built, signed and published by one workflow in
Blueprintr's agent repository, run for one version tag. Check each download
against that workflow's identity before you install it.

## Versions

Releases follow semantic versioning (MAJOR.MINOR.PATCH), tagged `v` and the
version, for example `v0.2.0`. Before 1.0, a minor version may change behaviour.
The version is the same in every file name, in the package metadata, in the
container tag and chart version, and in what `continuum-local --version` prints.
Release candidates are never offered on the download page.

The deb and rpm packages, the Windows installer, the container image and the
Helm chart are published from 0.2.0. Release 0.1.0 is the `.mjs` file only, for
Node.js 20.

## What a release contains

Every format runs the same `continuum-local-<version>.mjs` file: plain,
unminified JavaScript with no runtime dependencies. The deb, rpm and MSI include
a Node.js runtime whose checksum is verified when the release is built. The
container image is built on the official Node.js image, pinned by digest.

| File | What it is |
| --- | --- |
| `continuum-local_<version>_amd64.deb`, `_arm64.deb` | Packages for Debian and Ubuntu |
| `continuum-local-<version>-1.x86_64.rpm`, `.aarch64.rpm` | Packages for RHEL, Rocky and Alma |
| `continuum-local-<version>-x64.msi` | The Windows installer |
| `continuum-local-<version>.mjs` | The agent, for a host with Node.js 24 or later |
| `continuum-local-helm-chart-<version>.tgz` | The Helm chart, byte for byte the one in the registry |
| `config.example.json` | An example configuration |
| `SHA256SUMS`, `SHA256SUMS.cosign.bundle` | Checksums, and their signature |
| `continuum-local-<version>.mjs.cosign.bundle` | A signature over the `.mjs` file on its own |
| `continuum-local-<version>.cdx.json` | The SBOM, in CycloneDX 1.5 JSON |
| `continuum-local-<version>.sbom.att.bundle` | A signed attestation binding the SBOM to the `.mjs` file |
| `continuum-local-<version>-image.cdx.json` | The container image's package inventory |
| `continuum-local-<version>-image-amd64-vulnerabilities.json`, `-arm64-` | The container image's vulnerability scan at release time |
| `continuum-local-<version>-oci-digests.txt` | The container image's digest, and the chart's registry address |
| `PROVENANCE.txt` | A readable copy of the build claims in the signing certificate. It proves nothing on its own. |

`SHA256SUMS` lists the packages, the installer, the `.mjs` file, the chart
archive, the example configuration, the SBOMs, the scan reports and the digest
file. The signature bundles and `PROVENANCE.txt` are not in it. The container
image, `ghcr.io/blueprintr-io/continuum-local`
for linux/amd64 and linux/arm64, and the chart,
`oci://ghcr.io/blueprintr-io/charts/continuum-local`, are in GitHub Container
Registry under the same version.

If the Windows installer fails its build or its install test, the release is
published without it and its release notes say so. Windows estates then stay on
the previous release, or run the `.mjs` file on Node.js 24. A release is not
published at all if the scan of its container image finds a critical
vulnerability that has a fix available.

## Verify the downloads

Releases use Sigstore keyless signing. There is no long-lived signing key: each
signature is bound to the workflow file and the tag that produced it, and
recorded in Sigstore's public transparency log. Accept only this identity, the
release workflow at the tag you downloaded, issued by
`https://token.actions.githubusercontent.com`:

```text
https://github.com/blueprintr-io/continuum-local/.github/workflows/release.yml@refs/tags/v<version>
```

A signature from any other workflow, or from a branch, is not a release.
Download `SHA256SUMS`, `SHA256SUMS.cosign.bundle` and your files from the same
release, then run, with cosign 3.x (releases are signed with cosign 3.0.6):

```bash
V=0.2.0   # the version you downloaded
cosign verify-blob \
  --bundle SHA256SUMS.cosign.bundle \
  --certificate-identity "https://github.com/blueprintr-io/continuum-local/.github/workflows/release.yml@refs/tags/v${V}" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
```

The first command proves `SHA256SUMS` is the file the release workflow signed
for that tag. The second proves your downloads match it. A checksum without the
signature proves nothing, since anyone able to replace a download can replace
the checksum beside it. On Windows, compare the output of
`Get-FileHash .\continuum-local-<version>-x64.msi` with its line in the verified
`SHA256SUMS`.

The download page prints these commands, with the tag filled in, for the
release you are viewing.

### The container image and the chart

Both are signed by digest with the same identity:

```bash
V=0.2.0
ID="https://github.com/blueprintr-io/continuum-local/.github/workflows/release.yml@refs/tags/v${V}"
cosign verify ghcr.io/blueprintr-io/continuum-local:${V} \
  --certificate-identity "$ID" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
cosign verify ghcr.io/blueprintr-io/charts/continuum-local:${V} \
  --certificate-identity "$ID" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

Deploy the image by the digest `cosign verify` prints, which is also in
`continuum-local-<version>-oci-digests.txt`: a tag can be moved, a digest
cannot. Each platform's image is signed as well as the multi-platform index. An
admission controller such as Sigstore policy-controller or Kyverno can enforce
the identity on every pull with this pattern:

```text
^https://github\.com/blueprintr-io/continuum-local/\.github/workflows/release\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$
```

### The .mjs file and its SBOM

```bash
cosign verify-blob \
  --bundle continuum-local-${V}.mjs.cosign.bundle \
  --certificate-identity "$ID" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  continuum-local-${V}.mjs
cosign verify-blob-attestation \
  --bundle continuum-local-${V}.sbom.att.bundle \
  --type cyclonedx \
  --certificate-identity "$ID" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  continuum-local-${V}.mjs
```

The SBOM lists the agent's build tooling and what the packages redistribute:
the Node.js runtime, WinSW for the Windows service, and the container's base
image. The signing certificate in each bundle records the build claims
(repository, workflow, commit and run), and `PROVENANCE.txt` is a readable copy
of them.

## Supported versions and compatibility

While Continuum Local is below 1.0, only the latest release is supported.
Fixes, security fixes included, ship in a new release, and nothing is patched in
place. To report a vulnerability, follow
[Reporting a vulnerability](/foliums/blueprintr-user-guide/continuum/local-agent/security#reporting-a-vulnerability).

Agents and Blueprintr stay compatible across versions by these rules:

| Mechanism | What it means for you |
| --- | --- |
| Capabilities | On every poll the agent reports what it can do, and Blueprintr sends a job only to an agent that reported the capability the job needs. An older agent is never sent work it cannot do. A connector that needs a newer agent asks you to upgrade instead: WhatsUp Gold and Veeam Backup & Replication need 0.2.0 or later. |
| Additive changes | Fields in the protocol are only ever added. Capability names, job kinds and error codes are never reused for a new meaning. |
| Protocol version | The agent also reports a protocol version, reserved for a change that cannot be made by adding fields. Blueprintr speaks protocol 1 and accepts agents speaking protocol 1. An agent outside the accepted range is refused with HTTP 409, and its log says to upgrade Continuum Local. Blueprintr raises the oldest accepted protocol only after a deprecation window. |

Blueprintr decides what to send an agent from the capabilities it reports, not
from its version number. The panel shows the version number, and **Update
available** when a newer release exists. `continuum-local --version` prints both
the agent version and the protocol version.

## Release notes

Each release's notes are on the download page, under the version line: expand
**Release notes for 0.2.0**, or whichever version you are viewing. They give
that release's verify and install commands, and say when it has no Windows
installer. The page also marks the current release and shows the date each one
was released.

---

# Blueprintr User Guide: Upgrading and removing
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/upgrade-and-uninstall

> Upgrade or roll back Continuum Local on each platform, replace its credentials, revoke it in Blueprintr, and uninstall it.

An upgrade keeps the configuration, the enrolled identity and any credentials
sent from Blueprintr, so the agent needs no new token. An older agent keeps
working until you upgrade it, because Blueprintr sends an agent only the work it
reports it can do (see
[compatibility](/foliums/blueprintr-user-guide/continuum/local-agent/releases#supported-versions-and-compatibility)).
The Continuum Local panel shows each agent's version, and **Update available**
when a newer release exists.

## Upgrade

Download the new release,
[verify it](/foliums/blueprintr-user-guide/continuum/local-agent/releases#verify-the-downloads),
and set `V` to its version. Then:

| Install | Upgrade |
| --- | --- |
| Debian, Ubuntu | `sudo apt install ./continuum-local_${V}_amd64.deb` |
| RHEL, Rocky, Alma | `sudo dnf install ./continuum-local-${V}-1.x86_64.rpm` |
| Windows | Run the new `.msi`. |
| Docker | Pull the new image and replace the container, keeping the state volume (below). |
| Kubernetes | `helm upgrade agent oci://ghcr.io/blueprintr-io/charts/continuum-local --version $V --reuse-values` |
| Node.js host | Replace the `.mjs` file and restart the process. |

On Linux, a running agent restarts on the new version and a stopped one stays
stopped. On Windows, a service set to Automatic stays Automatic and restarts; a
Manual service stays Manual, and runs again after the upgrade if it was
running. In Kubernetes the old pod stops before the new one starts.

For Docker:

```bash
docker pull ghcr.io/blueprintr-io/continuum-local:$V
docker stop continuum-local && docker rm continuum-local
docker run -d --name continuum-local --restart=unless-stopped \
  -v /etc/continuum-local:/etc/continuum-local:ro \
  -v continuum-local-state:/var/lib/continuum-local \
  ghcr.io/blueprintr-io/continuum-local:$V
```

Upgrading a running agent restarts it. A request the agent was answering at
the time fails as not answered in time: refresh the tab once the agent is back
online. A network sweep that was running stops and is kept as a partial result,
so upgrade between scheduled sweeps. Afterwards,
confirm the new version in the panel or with `continuum-local --version`.

## Roll back

The [download page](https://blueprintr.io/download/continuum-local) lists
**Other versions** under the current release: the current release and a few
earlier ones, each with its own files and verify commands. For a version that
is no longer listed, email support@blueprintr.io.

Install the older release over the newer one, with `V` set to the older
version:

| Install | Roll back |
| --- | --- |
| Debian, Ubuntu | `sudo dpkg -i continuum-local_${V}_amd64.deb` |
| RHEL, Rocky, Alma | `sudo dnf downgrade ./continuum-local-${V}-1.x86_64.rpm` |
| Windows | Uninstall, then run the older `.msi`. The installer refuses to install over a newer version. |
| Docker | Run the older tag with the same state volume. |
| Kubernetes | `helm rollback agent`, or `helm upgrade` with the older `--version` |
| Node.js host | Run the older `.mjs` file. |

On Windows, uninstalling keeps `C:\ProgramData\Continuum Local`, so the
configuration and identity survive. The reinstalled service starts as Manual:
set it to Automatic and start it again. On every format, run `check` afterwards
and confirm the agent is online. If the older release lacks something a
connector needs, the connector list asks you to upgrade the agent.

## Replace the agent's credential

The agent keeps its own credential for Blueprintr in its state directory.
Replace it to rotate it, to move the agent to another machine, or to retire a
host you no longer trust.

> [!STEPS]
>
> === Issue a new token
>
> On the agent in the Continuum Local panel, choose **Re-enroll** and confirm.
> Blueprintr shows a new enrolment token and cancels any earlier unused one.
>
> === Put it in the configuration
>
> Set it as `enrollmentToken` in `config.json` on the machine that will run the
> agent.
>
> === Restart the agent
>
> It enrols again as the same agent, and the previous credential stops working.
> An install still using the previous credential is disconnected.
>
> === Remove the token
>
> Delete the `enrollmentToken` line.

If Blueprintr refuses the new token, the agent keeps its stored identity, says
so in its log, and does not send that token again. Credentials sent from
Blueprintr stay on the machine that received them. After a move, send them
again to the new machine, and delete the old machine's state.

A revoked agent cannot be re-enrolled. Create a new agent, set its token as
`enrollmentToken`, and restart. The agent enrols as the new agent and deletes
everything Blueprintr sent to the old one, so send those credentials again.

## Rotate a monitored system's credential

Blueprintr stores no credential for your on-premise systems, so you rotate one
in the monitored system and on the agent:

| Where the credential is | To change it |
| --- | --- |
| In `config.json`, a `credentialFile`, or a file or variable used in an `env:` or `file:` reference | Change the value, then restart the agent. The agent reads references once, when it starts. |
| Sent from Blueprintr | Choose **send credentials** on that connection again while the agent is online and connected to the gateway. The new value replaces the old one. |

On the Linux packages, the variables used in `env:` references are in
`/etc/continuum-local/environment`.

## Revoke or delete in Blueprintr

| Action | What happens |
| --- | --- |
| **Revoke** | The agent stops working at once: Blueprintr refuses its requests, closes its connection and drops its queued work. This cannot be undone. To use that machine again, create a new agent. |
| **Delete** | The agent is removed from Blueprintr with its network sweep results, and stops working at once if it is still running. The audit log keeps a record. |

Neither changes anything on the agent's machine. Credentials sent from
Blueprintr stay there until you choose **remove from agent** on each while the
agent is online and connected to the gateway, or delete the agent's state as
below.

## Uninstall

Uninstalling stops the agent and removes the program. It keeps the
configuration, with any credentials in it, and the state directory, with the
enrolled identity and any credentials sent from Blueprintr. Removing those is a
separate step:

| Install | Uninstall | Also remove the configuration and state |
| --- | --- | --- |
| Debian, Ubuntu | `sudo apt remove continuum-local` | `sudo apt purge continuum-local` deletes `/etc/continuum-local` and `/var/lib/continuum-local`. |
| RHEL, Rocky, Alma | `sudo dnf remove continuum-local` | rpm has no purge: `sudo rm -rf /etc/continuum-local /var/lib/continuum-local` |
| Windows | **Programs and Features** in Control Panel, or `msiexec /x continuum-local-<version>-x64.msi` | Delete `C:\ProgramData\Continuum Local`. |
| Docker | `docker stop continuum-local && docker rm continuum-local` | `docker volume rm continuum-local-state`, and the configuration directory on the host. |
| Kubernetes | `helm uninstall agent` | `kubectl delete pvc agent-continuum-local`, and the Secret you created: `kubectl delete secret continuum-local-config`. |
| Node.js host | Stop the process and delete the `.mjs` file. | Delete `config.json` and the state directory. |

On Linux, the `continuum-local` account stays after both remove and purge.
Delete it with `sudo userdel continuum-local`. Reinstalling after a plain remove
finds the kept configuration and leaves the service disabled until you enable
it. In Kubernetes, `helm uninstall` keeps the PersistentVolumeClaim, and removes
a Secret only when the chart created it from `config`.

To retire an agent completely:

1. Choose **remove from agent** for each credential sent from Blueprintr, while
   the agent is online and connected to the gateway. If it is not, step 3
   removes them.
2. Revoke or delete the agent in Blueprintr.
3. Uninstall it, and remove its configuration and state.

---

# Blueprintr User Guide: Troubleshooting
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/troubleshooting

> Finding out why a Continuum Local agent is offline or a request through it failed, with every error code the agent reports.

Start on the agent's host with
[`continuum-local check`](/foliums/blueprintr-user-guide/continuum/local-agent/configuration#the-check-command).
It tests the configuration, the state directory, the certificate roots, the
route to Blueprintr and a TLS handshake with each on-premise host, and says what
to change. It sends Blueprintr nothing beyond a TLS handshake, so it never
enrols, spends a token or claims work.

> [!CODETABS]
>
> === Debian, Ubuntu, RHEL
>
> ```bash
> sudo continuum-local check /etc/continuum-local/config.json
> ```
>
> === Windows
>
> ```powershell
> & "C:\Program Files\Continuum Local\runtime\node.exe" `
>   "C:\Program Files\Continuum Local\continuum-local.mjs" `
>   check "C:\ProgramData\Continuum Local\config.json"
> ```
>
> === Container
>
> ```bash
> docker run --rm \
>   -v /etc/continuum-local:/etc/continuum-local:ro \
>   -v continuum-local-state:/var/lib/continuum-local \
>   ghcr.io/blueprintr-io/continuum-local:<version> check
> ```
>
> === Bundle
>
> ```bash
> node continuum-local.mjs check ./config.json
> ```

On the Linux packages, run it with `sudo`: it then reads the service's
environment file and checks as the service account. On Windows, run it from an
elevated PowerShell, because only administrators and the service can read the
configuration folder.

## Logs

| Install | Logs |
| --- | --- |
| Debian, Ubuntu, RHEL, Rocky, Alma | `journalctl -u continuum-local` |
| Windows | `C:\ProgramData\Continuum Local\logs`. The service wrapper rolls the files by size and keeps eight |
| Container | `docker logs <container>` |
| Helm chart | `kubectl logs deploy/<release>-continuum-local` |
| Bundle | standard output and standard error, wherever your process supervisor sends them |

Each line is a JSON object. Warnings and errors go to standard error. The agent
masks each credential value it loaded before it writes a line, but host names
and addresses are not masked, so read a log before you send it anywhere.

A request the agent refuses is reported to Blueprintr with its code and does
not appear in the agent's log. Look for it where Blueprintr showed the failure.

## Error codes

When the agent cannot complete a request or a sweep, it reports one of these
codes. Blueprintr's message when **Verify** fails includes the code for most
of them, and a failed sweep shows the agent's own description on its results
page.

| Code | What happened | What to do |
| --- | --- | --- |
| `unknown_integration` | The agent has no entry for this integration in `config.json` and none sent from Blueprintr, or the entry's `provider` is not the connector the integration uses. | Send its credentials from the Continuum Local panel, or add its entry to the agent's `config.json`, then press **Verify**. Correct `provider` if it differs. |
| `host_not_allowed` | The integration's host is not in its `allowedHosts`. The same code covers an `http://` URL without `allowPlaintextHttp`, a redirect to another host with a credential in the URL or body, and a host sent from Blueprintr that resolves to an address the agent refuses. | Add the host to `allowedHosts` in the agent's `config.json`, or send the credentials again from the Continuum Local panel. See [Host not allowed](#host-not-allowed). |
| `credential_missing` | The agent has no credential for this integration, or the credential has no part with the name the connector needs. The message gives the part's name. | Send the credentials from the Continuum Local panel, or add them to the agent's `config.json` with the part names the panel shows. |
| `credential_unresolved` | The agent could not fill in the credential. A placeholder was left over, a part contains a line break or a character an HTTP header cannot contain, the system compressed a token response the agent asked it not to compress, or the agent no longer holds a sign-in token the system issued, usually after a restart. | Check the credential names on the agent match the Continuum Local panel, then press **Verify**. For a sign-in token the agent no longer holds, try again: a new one is fetched. If a placeholder was left over, upgrade the agent. |
| `upstream_unreachable` | The agent could not complete the request: DNS, a refused or reset connection, no route, more than three redirects, or a certificate it does not trust. | Check the base URL, and that the agent's machine can reach that system, then press **Verify**. For a certificate, see [Certificate errors](#certificate-errors). |
| `upstream_timeout` | The agent reached the system but it did not answer in time. | Check the system is healthy, then retry. |
| `deadline_exceeded` | The request's time ran out: the system did not finish responding, or the agent did not answer Blueprintr in time. | If the system was slow, check it is healthy and retry. If the agent did not answer, check that Continuum Local is still running and can reach Blueprintr, then press **Verify**. |
| `response_too_large` | The system's answer was larger than the request allows, the answer was too large to deliver in one poll to Blueprintr (about 1 MB), or a proxy refused a poll that contained only this result. | If the agent's log says Blueprintr refused a poll as too large, raise the request size limit on the proxy between the agent and Blueprintr. Otherwise, contact Blueprintr support with the integration and the time. |
| `unsupported_job` | This agent does not support this kind of request. | Upgrade the agent to the latest release, then try again. |
| `operation_not_allowed` | The agent's read-only guard refused the request. Nothing was changed. | See [Operation not allowed](#operation-not-allowed). |
| `discovery_not_configured` | A sweep was sent to an agent with no `discovery` block. | Add a `discovery` block to the agent's `config.json` and restart it. An agent older than 0.2.0 cannot report its ranges and needs upgrading first. |
| `cidr_not_allowed` | None of the ranges the sweep asked for is inside the agent's `discovery.cidrs`, or the agent lists no ranges. | Choose ranges inside `discovery.cidrs`, or add the range there and restart the agent. |
| `sweep_already_running` | The agent is already running a sweep, and it runs one at a time. | Start this one when the current sweep has finished, or cancel the current one. |
| `run_rejected` | Blueprintr refused the sweep's uploads, so the sweep stopped: the agent's credential was refused (HTTP 401), the first upload was refused, or the run was unknown, belonged to another agent or had already closed. | Start the sweep again. For HTTP 401, see [The agent is not accepted](#the-agent-is-not-accepted-http-401). |
| `agent_error` | Anything else. The message has the specifics, for example a `caFile` the agent could not read. | Act on the message. If it does not say what to change, contact Blueprintr support with the time and the agent's version. |

## Common failures

### The agent shows as offline

An agent counts as online when it has checked in within about ninety seconds.
When one has not been heard from for 15 minutes, Blueprintr emails the owners
and admins of the organisation that owns it, and of the team for a team's
agent. Each person gets at most one of these emails an hour, and none is sent
while Continuum Local is turned off in Blueprintr.

1. Check the service is running and the host is up.
2. Check that nothing blocks outbound HTTPS from the host to `blueprintr.io`
   and `agents.blueprintr.io`: a firewall rule, a proxy change, or a
   TLS-inspecting proxy whose root the agent does not trust. See
   [Network requirements](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements).
3. Run `continuum-local check`.
4. Read the agent's log for the reason it gives.

### Continuum Local is turned off in Blueprintr

The panel says so, and the agent's log shows HTTP 503 with a message that
says the same.
Blueprintr has turned Continuum Local off for every customer for a while, for
example during an incident. Nothing is wrong on your side. Agents keep their
configuration and reconnect on their own when it is turned back on, and no
sweep can start until then.

### The agent is not accepted (HTTP 401)

The log says Blueprintr rejected this agent's credential. The agent was revoked
or deleted in Blueprintr, or enrolled again on another machine. Create a new
agent in Blueprintr, put its token in `config.json` as `enrollmentToken`, and
restart the service. The new token re-enrols this install in place, so nothing
on disk needs deleting. Credentials sent from Blueprintr to the old agent are
removed and need sending again. Until then the agent retries every five
minutes.

### Enrolment fails

- On a first start, a `Fatal` line whose error ends
  `answered HTTP 401: Enrollment failed.` means the token was spent, expired or
  revoked: Blueprintr gives the same answer for each. Create a new token with
  **New token** in the Continuum Local panel, or for a revoked agent, create a
  new agent.
- An answer about the plan means the organisation that owns the agent has no
  active Enterprise plan. The token is not spent: once an owner renews the plan,
  restart the agent within the token's 24 hours.
- A token in `config.json` that Blueprintr refused on an agent that is already
  enrolled leaves the old identity in place, and the agent says so at start.
- A state directory the agent cannot write to is reported, with advice for
  the platform, before the token is sent.

### Blueprintr does not support the agent's protocol (HTTP 409)

Blueprintr does not support the protocol version this agent speaks. The log
says to upgrade to the latest release, and the agent retries every 30 minutes
until then. An upgrade keeps the configuration, the enrolled identity and any
integrations sent from Blueprintr, and needs no new token.

### The plan is inactive (HTTP 403)

The organisation that owns the agent no longer has an active Enterprise plan,
and the agent is paused. It keeps retrying and reconnects on its own once an
owner renews the plan.

### Certificate errors

Between the agent and Blueprintr, a failed certificate check usually means a
proxy that inspects TLS. `check` reports the certificate as not trusted and
shows the issuer. Give the agent the proxy's root certificate, in PEM form, as
`extraCaFile`.

Between the agent and an on-premise system, the request fails with
`upstream_unreachable`, and the message says whether the certificate is
self-signed, issued by an authority the agent does not trust, expired, not yet
valid, or does not name the host.

- For an untrusted certificate, set `caFile` on the integration to the
  certificate, or to the one from the authority that issued it, rather than
  turning certificate checks off.
- For a name mismatch, `check` lists the names the certificate contains. The
  integration's URL in Blueprintr and `allowedHosts` must use one of them.
- For an expired certificate, renew it on the system.
- Infoblox NIOS needs its certificate replaced first: see
  [Certificates](/foliums/blueprintr-user-guide/continuum/local-agent#certificates).

`allowInsecureTls` accepts any certificate from that integration's hosts. Use it
only when the system cannot present one the agent can verify.

### Host not allowed

`allowedHosts` must contain the host exactly as it appears in the
integration's URL in Blueprintr. A host name and an IP address for the same machine are
different entries. For an integration sent from Blueprintr, the host must also
fit `remoteCredentialScope`, and the address it resolves to is checked at every
connection. Add the host to `allowedHosts` in the agent's `config.json`, or send
the credentials again from the Continuum Local panel.

### Operation not allowed

The agent relays only requests it recognises as reads for that product.
Blueprintr's message says which case applied, and nothing was changed in any of
them.

| Blueprintr's message says the request | What to do |
| --- | --- |
| is not one of the connector's reads | The agent is probably older than the connector. Upgrade it to the latest release, then press **Verify**. |
| is not a read at all | Try upgrading the agent first. Only if the integration must change something in that product, set `"allowWriteOperations": true` on its entry in `config.json` and restart the agent. Blueprintr can never set it. |
| failed one of the agent's safety checks on the request itself | This is not a sign the integration needs write access, so leave `allowWriteOperations` off. If it keeps happening, contact Blueprintr support. |
| belongs to an integration configured from Blueprintr for a product the agent has no read rules for | Add the integration to the agent's `config.json` instead, or upgrade the agent. |

### Proxy problems

`check` shows the proxy it used and tells its failures apart from a firewall's:

| `check` says | Fix |
| --- | --- |
| the proxy wants a user name and password (407) | Write `proxy` as `http://user:password@host:port`, ideally behind `env:` or `file:` |
| the proxy refused the tunnel | Allow CONNECT to port 443 on `blueprintr.io` and `agents.blueprintr.io` |
| the proxy refused the connection, or its host name does not resolve | Correct the proxy's host and port |
| no answer within the timeout: a firewall is probably dropping the connection | The host has no direct route out. Set the proxy where the service reads it: see [Proxies](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements#proxies) |

An agent on Node.js older than 24 refuses to start with a proxy configured. Use
a package or the container, which include Node.js 24, or upgrade Node.js for the
bundle. If the agent's log says Blueprintr refused a poll as too large, a proxy
between them may limit request size: raise its limit for the Blueprintr hosts.

---

# Blueprintr User Guide: Questions and limitations
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/continuum/local-agent/faq

> Air-gapped networks, proxies, where credentials and data are kept, several agents and sites, redundancy, a lapsed plan, and how long a release is supported.

## Does it work on an air-gapped network?

No. The agent needs outbound HTTPS on port 443 to `blueprintr.io` and
`agents.blueprintr.io`. Every job comes from Blueprintr and every result goes
back to it, so there is no offline mode and nothing is stored locally to upload
later. It suits private and firewalled networks: nothing connects inward, so no
inbound rule is needed.

## Can it go through our proxy?

Yes, for its traffic to Blueprintr. Set
[`proxy` and `noProxy`](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements#proxies)
in `config.json`, or `HTTPS_PROXY` and `NO_PROXY` in the agent's environment.
Connections to your own systems and SNMP sweeps never use the proxy. For a
proxy that inspects TLS, give the agent the proxy's root certificate as
`extraCaFile`, which it trusts for Blueprintr only. If the proxy blocks the
WebSocket to `agents.blueprintr.io`, the agent polls instead.

## Where are our credentials stored?

On the agent's host, in the places listed under
[Where credentials are kept](/foliums/blueprintr-user-guide/continuum/local-agent/security#where-credentials-are-kept).
Credentials you configure are in `config.json`, or in the environment
variables and files it refers to, or in a `credentialFile` your secret manager
writes. Credentials sent from Blueprintr, which is off unless you set
`allowRemoteCredentials`, are written to the agent's state directory.
Blueprintr stores none of them, and for credentials in `config.json` it never
receives the value.

## Where is our data stored?

The agent sends Blueprintr its own status, the answers to the jobs it runs and
its sweep results. Blueprintr keeps its records of agents, relay jobs, saved
panels and sweeps in its application database, and
[What Blueprintr stores](/foliums/blueprintr-user-guide/continuum/local-agent/security#what-blueprintr-stores)
says what each record contains, who can see it and how long it is kept.
Blueprintr's [privacy policy](https://blueprintr.io/privacy) places the
application and its database in Amazon Web Services in Ireland (`eu-west-1`),
with Cloudflare in front of it.

## Can we run several agents, or one per site?

Yes. An organisation or team can have up to 25 agents, each with its own name,
configuration and discovery ranges. Revoked agents count towards that until you
delete them. Put each site's systems in the configuration of the agent at that
site.

Each agent reports the integration IDs in its configuration, and those sent to
it from Blueprintr. Blueprintr sends a
request for an integration only to an online agent that reports it, preferring
the one heard from most recently, and keeps the requests of one operation on
one agent. An agent older than 0.2.0 reports no list, and is used only when no
agent lists the integration. A team's integrations can use the team's own agents
and its parent organisation's. A sweep runs on the agent you choose, within that
agent's ranges.

## Is there high availability?

There is no clustering. Each agent is one process with its own identity. Two
copies of one identity would take jobs from the same queue, so run each agent
once: the Helm chart runs one replica for that reason, and enrolling the same
agent on another host cuts off the first.

For redundancy, enrol a second agent and add the same integrations to its
`config.json`. When one agent stops polling, requests for those integrations go
to the other. These stay with one agent:

- sweeps and sweep schedules, which belong to one agent. A scheduled sweep whose
  agent is offline is skipped;
- credentials sent from Blueprintr, which go to one agent. Give a standby agent
  its credentials in `config.json`;
- WhatsUp Gold and Veeam Backup & Replication tokens, which stay on the agent
  that obtained them. The other agent obtains its own.

## What happens if our Enterprise plan lapses?

Continuum Local is judged on the plan of the organisation that owns the agent,
and a team's agent uses its parent organisation's plan. Within about five
minutes of a lapse:

- the agent's polls are refused with a message in its log saying the plan is
  inactive. It keeps its configuration, keeps retrying, and resumes on its own
  once an owner renews;
- enrolment is refused, and the enrolment token is not used up;
- on-premise tabs keep their last saved snapshot and cannot be refreshed;
- no sweep can start, scheduled sweeps are skipped, and past sweeps cannot be
  viewed until the plan is active again. The 90-day retention keeps running
  meanwhile, apart from each agent's latest complete sweep, which is kept until
  a newer one completes;
- the Continuum Local panel lists the agents as paused, with **Revoke**,
  **Delete** and **remove from agent** only, so you can take them out of
  service.

Nothing on the agent's host is deleted: its configuration and any credentials
sent from Blueprintr stay there until you remove them. A paused agent's polls
are refused, so **remove from agent** usually reports it offline. Remove those
credentials on the agent's machine instead, by deleting its state as described
under
[Uninstall](/foliums/blueprintr-user-guide/continuum/local-agent/upgrade-and-uninstall#uninstall).

## How long is a release supported?

Until the next one. Before version 1.0 only the latest release is supported.
Fixes, including security fixes, ship in a new release, and nothing is patched
in place. The download page offers the current release and a few before it, so
you can install the version your change control approved or roll back.
Blueprintr sends an agent only work it
[reports it can do](/foliums/blueprintr-user-guide/continuum/local-agent/releases#supported-versions-and-compatibility),
so an older agent keeps working, and a connector that needs a newer one says to
upgrade. The agent never updates itself.

## Other limits

- Sweeps are IPv4 only. Each block in `discovery.cidrs` is a /22 at most unless
  you set a smaller `maxSweepPrefix`, and never larger than a /16.
- Discovery uses SNMP only. There is no ICMP ping sweep or port scan.
- An agent runs one sweep at a time, for 5.5 hours at most.
- Sweep results appear only on the sweep pages in settings. Nothing draws them
  on a diagram or attaches them to a stratum.
- Credentials can be sent from Blueprintr only to an agent that is online and
  connected to `agents.blueprintr.io`. Nothing is queued for an offline agent.
- A linked tab changes only when an editor refreshes it. Nothing runs on a
  schedule apart from the sweep schedules you set.

---

# Blueprintr User Guide: AI
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/ai

> Where AI appears, what each surface is allowed to do, and how it is paid for.


Each AI surface is scoped narrowly, and none of them acts without you seeing
what it is about to do.

| Where | Does |
| --- | --- |
| [AI Assist](/foliums/blueprintr-user-guide/ai/ai-assist) | Answers questions and performs actions across your workspace |
| [Drawing](/foliums/blueprintr-user-guide/ai/drawing-with-ai) | Generates and edits diagrams on the canvas |
| [Import](/foliums/blueprintr-user-guide/ai/importing-with-ai) | Turns documents and images into blueprints and diagrams |
| [The docs assistant](/foliums/blueprintr-user-guide/foliums/docs-assistant) | Answers questions about one folium, for its readers |

## The boundary

> [!IMPORTANT]
> No AI surface in Blueprintr holds staff authority, and none can perform
> administrative or destructive actions. It cannot change access control, grant
> permissions, delete content, or touch billing, regardless of what it is
> asked.

Actions that change your content are **confirm-first**: the agent proposes,
shows you exactly what it will do, and waits.

## Paying for it

Free accounts get a monthly allowance measured in *uses*. Paid accounts spend
*credits*. Both are set out on
[credits and allowances](/foliums/blueprintr-user-guide/ai/credits-and-allowances).

---

# Blueprintr User Guide: AI Assist
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/ai/ai-assist

> A question box over your own content that can also act, with your confirmation first.

AI Assist is in the navigation bar. Ask it about your content, or ask it to do
something.

## What it can see

Your blueprints, folia and diagrams, scoped to what you already have access to.
It also searches the official Blueprintr documentation, so product questions
are answered from the same box.

## Actions

It can create and edit content on your behalf. Every action that changes
something is shown to you first, in full, and does not run until you confirm.

> [!IMPORTANT]
> It cannot administer anything. Permission changes, sharing changes, deletions
> and billing are outside what it can do. If you ask for one of those, it will
> tell you it cannot rather than attempting it.

## Getting good answers

Name the thing. "In the payments blueprint, what does the retry queue do" beats
"how do retries work": the first is answerable from your content, the second is
a question about the world.

## Turning it off

**Settings → AI** controls whether AI features are available to you.
Organisations can disable them for everyone, and can set per-member limits.

---

# Blueprintr User Guide: Drawing with AI
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/ai/drawing-with-ai

> Generating a diagram from a description, converting an image of one, and editing by asking.

The Vellum canvas has an AI panel. Describe what you want and it draws it;
select shapes and ask for a change and it edits them.

![The Vellum AI panel: Draw, Convert and Explain tabs above a prompt box, with example questions and the credit balance at the foot](/api/folium-assets/cmtp09lf6009tndrb2iu0lojy/raw)

## Draw, Convert, Explain

The panel opens with three modes. **Draw** produces shapes. **Convert** turns
an image of an existing diagram into an editable one, opening the import dialog
rather than starting a conversation. **Explain** answers questions about the
diagram in front of you, such as "what does this show?" or "where's the
bottleneck?", and will not touch the drawing unless you ask it to.

The panel header names the current scope, so you can see whether you are asking
about one selected shape or the whole canvas before you send.

## Generating

Describe the system in prose. Be specific about the parts and how they connect:
the model draws what you name, and invents structure where you leave gaps.

Generation produces an ordinary diagram. Every shape is editable, and there is
no separate "AI layer" to unpick later.

## Editing

Select shapes and describe the change. With a selection, the edit is confined
to it; with nothing selected, the whole diagram is in scope.

## Expect to finish it yourself

> [!TIP]
> Generation gets you a workable draft, not a finished diagram. Layout,
> grouping and colour still need your judgement.

## Cost

Generation and editing draw on your
[allowance or credits](/foliums/blueprintr-user-guide/ai/credits-and-allowances). A failed
generation still costs, because the work was done even if you did not like the
result.

---

# Blueprintr User Guide: Importing with AI
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/ai/importing-with-ai

> Turning documents, images and existing diagrams into blueprints.

AI import reads source material and produces a blueprint: a diagram, plus the
prose around it.

## What it accepts

Documents, images of diagrams, and diagram files in formats that can be parsed.
An image of a whiteboard becomes an editable diagram rather than a picture of
one.

## What you get

A draft, owned by you, private until you publish it. Nothing is published
automatically.

Icons are resolved against the icon packs where the source suggests a
recognisable vendor or service, so an imported cloud diagram arrives with the
right marks rather than grey boxes.

## Review it

> [!IMPORTANT]
> Check the result against the source before publishing. Import infers
> structure, and inference is occasionally confidently wrong. The failure mode
> is a diagram that looks plausible and says something untrue.

## Bulk

[Bulk import](/foliums/blueprintr-user-guide/organise/importing-content) runs the same
conversion across many files, with a mapping step first.

---

# Blueprintr User Guide: Credits and allowances
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/ai/credits-and-allowances

> Free accounts get a monthly allowance in uses; paid accounts spend credits. What each covers.


How AI use is metered depends on your plan.

## Free accounts

A monthly allowance counted in **uses**, not credits:

| Allowance | Covers |
| --- | --- |
| Diagram generations | Drawing and editing with AI |
| Assistant turns | A pooled monthly count across AI surfaces |

There is also a platform-wide daily ceiling. On a busy day the free allowance
can be temporarily unavailable even if your own monthly count is not exhausted.

## Paid accounts

Paid plans spend **credits**. Each action reserves an estimate up front and
settles to the actual cost when it completes.

> [!IMPORTANT]
> A failed or abandoned action is not free. The work was performed, so it
> settles at what it cost. Cancelling a long generation part-way saves only the
> work not yet done.

## Organisation caps

An organisation can set per-member caps so one person cannot spend the shared
pool. Caps are visible to the member.

## Where to look

**Dashboard → Licensing & Billing** shows your balance or remaining allowance,
and what has been spent. Organisation-wide usage is under the organisation's
credits page.

---

# Blueprintr User Guide: Account
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/account

> Where to find each setting, across account, security, notifications, AI, libraries and data.


**Dashboard → Settings**. Personal settings are yours across every workspace;
organisation settings sit on the organisation.

![The settings navigation, grouped into an unlabelled first group, then Security, Billing, Privacy and Developer](/api/folium-assets/cmtp00y7k0001c558ac0rbqa4/raw)

| Page | Holds |
| --- | --- |
| General | Display name, handle, default diagram engine |
| Account | Email, password, account deletion |
| Notifications | What Blueprintr emails you about |
| Libraries | Icon packs enabled for your diagrams |
| Teams & orgs | Organisations and teams you belong to |
| [Security](/foliums/blueprintr-user-guide/account/security) | Two-factor and passkeys |
| Sessions & devices | Everywhere you are signed in |
| Connected accounts | Google, GitHub and other sign-in providers |
| [Licensing & billing](/foliums/blueprintr-user-guide/account/billing-and-usage) | Plan, seats, credits, invoices |
| Visibility | Defaults for new content |
| [Data & privacy](/foliums/blueprintr-user-guide/account/your-data) | Export and deletion |
| API keys & MCP | [Personal keys](/foliums/blueprintr-user-guide/developers/api-keys-and-scopes) and the MCP server |

---

# Blueprintr User Guide: Security
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/account/security

> Two-factor authentication, passkeys, and seeing where you are signed in.

![blueprint:josh/securing-your-account](https://blueprintr.io/embed/josh/securing-your-account?exclude=cmtpwdx7j000jybbheum4kptm&hideTabBar=1#h=620)

## Passkeys

A passkey is held by your device or password manager, cannot be phished, and
signs you in with the same gesture you unlock your device with.

Register more than one, such as a phone and a laptop, or a passkey and a
hardware key, so losing a device does not lock you out.

## Two-factor authentication

An authenticator app generating a time-based code, as a second step after your
password.

> [!IMPORTANT]
> Save your recovery codes somewhere that is not the device running the
> authenticator.

## Sessions

**Settings → Sessions & devices** lists everywhere you are currently signed in,
with device and approximate location. Revoke any you do not recognise.

Signing out revokes the session everywhere it is held, including the desktop
app.

## Organisation requirements

An organisation can require two-factor authentication for its members. Where it
does, you will be asked to set it up before you can reach the organisation's
content.

---

# Blueprintr User Guide: Plans
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/account/plans

> What each tier includes, and which gate decides each feature.

Four tiers: **Free**, **Premium**, **Team** and **Enterprise**. Each inherits
everything below it.

Current prices are on the [pricing page](https://blueprintr.io/pricing). This
page covers what each tier includes.

## Free

Everything needed to draw, publish and share: blueprints, strata, Vellum,
foliums, portfolios, and public or unlisted publishing.

AI is metered in **uses** rather than credits:

| | |
| --- | ---: |
| Diagram generations | 5 / month |
| Conversation turns (Ask AI, AI Assist) | 50 / month |
| Storage | 500 MB |

Ask AI and AI Assist are open to free accounts. Assist is confirm-first, and
every action it proposes re-checks the permission you would need to do it by
hand.

## Premium

Personal tier. Adds:

- [Analytics](/foliums/blueprintr-user-guide/blueprints/analytics), per blueprint and per workspace
- [Embedding](/foliums/blueprintr-user-guide/sharing/embedding-blueprints) a blueprint elsewhere
- The [import wizard](/foliums/blueprintr-user-guide/organise/importing-content), and Podium frame import
- Live Vellum [collaboration](/foliums/blueprintr-user-guide/vellum/live-collaboration) and its invites
- The editor's AI writing assistant
- Storage to 5 GB, and AI metered in credits rather than counts

> [!NOTE]
> Analytics is gated on the **author's** plan, not the reader's. A blueprint by
> a free author has no analytics even for a premium colleague who can edit it.

## Team

Requires a [Teams-licensed organisation](/foliums/blueprintr-user-guide/teams/setting-up-an-organisation).
Adds everything that involves more than one person, plus the estate-facing half
of the product:

- [Version history](/foliums/blueprintr-user-guide/blueprints/versions-and-history): snapshots, diffs and restore
- [Approval workflows](/foliums/blueprintr-user-guide/teams/reviews-and-approvals) and change requests
- [Continuum](/foliums/blueprintr-user-guide/continuum) cloud discovery: connect an account, scan it, draw it
- Teams, roles and the [audit log](/foliums/blueprintr-user-guide/teams/audit-log)
- Storage to 20 GB per team and per organisation

Continuum's discovery pipeline has caps at this tier:

| | |
| --- | ---: |
| Cloud connections per owner | 3 |
| Scopes per integration | 3 |
| Resources per integration | 200 |
| Integrations per owner | 5 |
| Integration tabs per stratum | 8 |

## Enterprise

Everything above, without most of those caps. Connections, scopes, resources
and integrations become unlimited, integration tabs per stratum go to 20, and
storage to 100 GB.

One capability is Enterprise-only rather than a raised cap:

> [!IMPORTANT]
> The **Continuum Integration Engine** is Enterprise: the PagerDuty,
> ServiceNow, GitHub, GitLab and CloudWatch connectors, the Continuum-Link bind
> flow, and blueprint Scan. Continuum's cloud discovery (connect → scan → draw)
> is Team. They are two separate gates, and having one does not give you the
> other.

Plus the tenancy controls: [SSO](/foliums/blueprintr-user-guide/enterprise/single-sign-on),
[SCIM](/foliums/blueprintr-user-guide/enterprise/scim-provisioning), IP allow-listing,
content classification and white-label domains.

Enterprise is quoted rather than bought from a page, and the
[Enterprise](/foliums/blueprintr-user-guide/enterprise) section covers the rest.

## Which gate am I hitting?

A feature that refuses usually names its tier.

- **Version history** is Team, so a Premium author still has snapshots taken
  but cannot browse them.
- **Analytics** is Premium *on the author*, so it can be unavailable on a
  blueprint you can edit.

---

# Blueprintr User Guide: Billing and usage
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/account/billing-and-usage

> Where your licence, seats, AI credits and storage are shown, and what happens when one runs out.

**Dashboard → Licensing & Billing** holds everything personal. Organisation
billing sits on the organisation and needs `license.read`.

## What is on it

| Panel | Shows |
| --- | --- |
| Your licence | Current plan, status, and the switch between monthly and annual |
| AI credits | Balance, or the remaining free allowance |
| Your organisations | Each org you belong to, its licence and its seats |
| Self-service billing | Invoices, payment method and the customer portal |

Prices are shown in the billing currency fixed when you first subscribe.

## Seats

A Teams licence is bought for an organisation, from that organisation's
**Settings → Billing**. The sequence is on
[Setting up an organisation](/foliums/blueprintr-user-guide/teams/setting-up-an-organisation).
It is bought in seats, and the seat count is the subscription quantity.
Changing it is a subscription change. The org's licence panel is the authority
on how many are used.

## AI credits

Paid plans meter AI in **credits**; the free tier meters in
[uses instead](/foliums/blueprintr-user-guide/account/plans). Credits are consumed by
generation, the assistant, and the editor's AI.

> [!IMPORTANT]
> A failed generation still costs. The work was done and paid for upstream
> whether or not you liked the answer, and no refund is issued automatically.
> Budget for a retry.

Credit packs top up separately from the plan and do not expire at the end of a
billing period.

### If a pack is refunded

Refunding a credit-pack charge takes the credits back. How the reversal is
calculated:

> [!FIELDS]
>
> > [!FIELD Cumulative, not per-event|idempotent]
> >
> > The reversal targets how many credits *should* be gone given everything
> > refunded so far, then acts on the difference. A replayed webhook resolves
> > to nothing; a second partial refund reverses only the new slice.
>
> > [!FIELD Monotonic|one-way]
> >
> > The target never decreases, so an out-of-order event can never hand
> > credits back. Restoring credits is an operator decision.
>
> > [!FIELD Floors at zero|no debt]
> >
> > If you already spent below the refunded amount, the balance goes to zero
> > and the shortfall is recorded. You are never carried at a negative
> > balance.

## Storage

Uploads count against the owner's quota: 500 MB free, 5 GB premium, 20 GB per
team or organisation, 100 GB enterprise. A single file is capped at 20 MB and a
single diagram document at 5 MB.

> [!TIP]
> A write that **reduces** your total is never rejected, whatever your quota
> says. If you are blocked, delete something and continue. You do not need the
> limit raised first.

Hitting the 5 MB document ceiling usually means a diagram has grown into
something that wants splitting rather than compressing.
[Files and folders](/foliums/blueprintr-user-guide/blueprints/files-and-folders) lists
what counts toward the total and what does not.

---

# Blueprintr User Guide: Your data
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/account/your-data

> Requesting an export, deleting an account, and which audit records are retained.


**Settings → Data & privacy.**

## Export

**Request data export** queues an export of your content. It is processed in
the background, and you are notified when it is ready.

For documentation specifically, the
[CLI](/foliums/blueprintr-user-guide/foliums/docs-cli) pulls a folium to disk as ordinary
markdown. This route round-trips: edit the files and push them back.

A folium also has its own
[export](/foliums/blueprintr-user-guide/foliums/export-and-print): a static site or a
printable document, resolved for whichever audience you pick.

## Deleting your account

**Permanently delete my account** asks for your current password first, so a
session someone walked away from cannot delete an account.

> [!IMPORTANT]
> Content owned by an organisation or a team **stays with it**: deleting your
> account does not delete a team's documentation. Move anything you want to
> keep personally before you delete.

Deletion is not instant, and cannot be undone once it completes. Export first.

## What is kept

[Audit records](/foliums/blueprintr-user-guide/teams/audit-log) of consequential actions
are retained by the organisation they belong to. The table is append-only at
the database level, so there is no path to remove them.

Those entries record the action and the actor id, not your profile. The request
context they include is a **hash** of the IP address.

---

# Blueprintr User Guide: Developers
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/developers

> What REST, MCP, webhooks and the CLI each do, and which one to use.


| Surface | Use it when |
| --- | --- |
| [REST API](/foliums/blueprintr-user-guide/developers/rest-api) | Your code reads or writes content |
| [MCP server](/foliums/blueprintr-user-guide/developers/mcp-server) | An AI agent works with your account |
| [MCP tool reference](/foliums/blueprintr-user-guide/developers/mcp-tool-reference) | You need to know exactly what an agent can call |
| [Webhooks](/foliums/blueprintr-user-guide/developers/webhooks) | You react to something happening |
| [CLI](/foliums/blueprintr-user-guide/foliums/docs-cli) | You author documentation in a text editor |

All of them authenticate with the same
[API keys](/foliums/blueprintr-user-guide/developers/api-keys-and-scopes) and honour the
same access rules. Nothing reachable programmatically is wider than what the
key's owner can already see.

## The common boundary

> [!IMPORTANT]
> There are no delete, sharing, billing, account or administrative operations
> on the agent-facing surfaces. Content visibility can only change through the
> constrained publish operations. A key cannot be used to grant access to
> another person.

---

# Blueprintr User Guide: API keys and scopes
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/developers/api-keys-and-scopes

> The two kinds of key, the scopes available to each, and what every scope unlocks.

Mint keys at **Dashboard → Settings → API keys & MCP**
(`/dashboard/settings/developer`). The plaintext is shown once; Blueprintr
stores only a hash of it.

## Two kinds of key

The prefix tells you which. They are separate credentials: they reach
different servers and are offered different scopes.

![blueprint:josh/two-keys-two-servers](https://blueprintr.io/embed/josh/two-keys-two-servers#h=540)

## Personal key scopes

Ten, and every one of them is optional.

| Scope | Unlocks | Tools |
| --- | --- | ---: |
| `read:blueprints` | Blueprints, portfolios, strata, diagram tabs, templates, tags, analytics, change requests | 20 |
| `read:vellums` | Standalone vellum diagrams, including `docYaml` | 2 |
| `read:foliums` | Foliums, their pages and their strata | 4 |
| `read:organization` | The orgs and teams you belong to, so an agent can file work in the right workspace | 4 |
| `search` | Search across everything the key can already see | 1 |
| `write:blueprints` | Create and update your own drafts, publish them, build strata and diagram tabs, manage portfolios | 22 |
| `write:vellums` | Create and update vellums you can edit | 6 |
| `write:foliums` | Create and update foliums, pages and folium strata | 7 |
| `write:sharing` | Narrow a blueprint's audience | 2 |
| `write:review` | Submit your own work into a governance workflow | 3 |

`write:sharing` is monotonic. Its two tools, `restrict_blueprint_audience` and
`raise_blueprint_classification`, can only ever make content *more* private.
No tool widens an audience, so a leaked key cannot publish your private work.

There is no `write:organization`. Membership and roles stay out of scope
permanently, and tenant cosmetics are excluded because a mistake there reaches
every user in the organisation.

## Organisation key scopes

Five. Names shared with the personal list mean different things here.

| Scope | Unlocks |
| --- | --- |
| `read:blueprints` | Public blueprints belonging to the organisation |
| `read:docs` | Public folium pages |
| `read:private-docs` | Private folium pages as well, gated to owners and admins at mint time |
| `search` | Search within that scope |
| `mcp` | The host-scoped documentation MCP server, on an org or team subdomain |

Grant `read:private-docs` only where the key needs private pages. It turns a
key that reads your published documentation into one that reads all of it.

## Choosing scopes

New keys default to read-only, and scopes **cannot be edited after creation**.
Minting a new key is the only way to change them.

> [!IMPORTANT]
> A personal key with a write scope acts as you, with your access. Store it in
> a secret manager, never in source control, and never in a command-line flag:
> argv is visible in `ps` and lands in shell history. Pass it through an
> environment variable or a file instead.

## Limits

| | |
| --- | ---: |
| Active personal keys per user | 10 |
| Key creations per hour | 10 |
| Requests per key, per 5 minutes | 600 |
| Requests per IP, per 5 minutes | 60 |
| Write tool calls per key, per 5 minutes | 40 |

## Checking a key

`whoami` needs no scope. It reports whether the key is live and what it can
do, in one call:

```bash
curl -fsS https://blueprintr.io/api/mcp \
  -H "Authorization: Bearer $BLUEPRINTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"whoami","arguments":{}}}' \
  | jq -r '.result.content[0].text | fromjson | {username, plan, scopes}'
```

A live personal key returns your handle, plan and its scopes. If it returns
the public documentation tool set instead, the key was not accepted: it is
missing, malformed or revoked.

## Rotating

Use one key per client, so a single connection can be revoked without breaking
the others. Revocation takes effect on the next request.

Rotate in this order: mint the replacement, deploy it, confirm with `whoami`,
then revoke the old one.

---

# Blueprintr User Guide: REST API
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/developers/rest-api

> Every /api/v1/docs route with the scope it needs, plus the concurrency rule that stops two writers overwriting each other.

The versioned REST API is at `/api/v1`. Authenticate with a bearer token.

```bash
curl -fsS https://blueprintr.io/api/v1/docs \
  -H "Authorization: Bearer $BLUEPRINTR_TOKEN"
```

## Routes

`{ref}` is a folium slug or id. **Personal keys only** means a `bpk_user_…`
key. An organisation key on those routes is refused with `403`, not a `404`.

| Route | Scope | Does |
| --- | --- | --- |
| `GET /docs` | `read:foliums` | Foliums you can author |
| `GET /docs/{ref}` | `read:foliums` | The page tree. `?status=all` includes drafts |
| `GET /docs/{ref}/pages` | `read:foliums` | Flat page list |
| `POST /docs/{ref}/pages` | `write:foliums` | Create a page |
| `GET /docs/{ref}/pages/{path}` | `read:foliums` | One page by its reader path |
| `GET /docs/{ref}/page/{pageId}` | `read:foliums` | One page by id |
| `PATCH /docs/{ref}/page/{pageId}` | `write:foliums` | Edit content or metadata |
| `DELETE /docs/{ref}/page/{pageId}` | `write:foliums` | Archive a page and its subtree |
| `POST /docs/{ref}/page/{pageId}/move` | `write:foliums` | Reparent or reorder |
| `POST /docs/{ref}/page/{pageId}/publish` | `write:foliums` | Publish or retract one page |
| `GET /docs/{ref}/search` | `read:foliums` | Search within the folium |
| `GET /docs/{ref}/diagnostics` | `read:foliums` | The last run |
| `POST /docs/{ref}/diagnostics` | `write:foliums` | Run the rules now |
| `GET /docs/{ref}/versions` | `write:foliums` | Published versions |
| `POST /docs/{ref}/versions` | `write:foliums` | Snapshot the published set as a version |

Version routes are edit-gated in both directions, including the `GET`. The list
alone tells a public reader how a document has been managed.

## Creating and editing a page

```bash
curl -fsS -X POST https://blueprintr.io/api/v1/docs/handbook/pages \
  -H "Authorization: Bearer $BLUEPRINTR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Deploying",
        "parentId": null,
        "kind": "doc",
        "content": "# Deploying\n\nOne command.",
        "description": "How a release reaches production.",
        "icon": "rocket",
        "hideInNav": false,
        "status": "draft"
      }'
```

Strings past their ceiling are **clamped rather than rejected**, matching what
the app itself does. Only shape errors come back as errors, because those are
the ones a caller can fix.

`PATCH` takes any subset of `title`, `description`, `content`, `icon` and
`hideInNav`.

> [!IMPORTANT]
> `PATCH` will not accept `status`, `kind` or `slug`.
> A content edit must never publish a draft somebody held back, as a side
> effect of one stray field. Publishing has its own route so it has its own
> audit line; a `kind` change turns a content page into a pointer; a slug
> change is a URL move, which is what `/move` is for.

## Publishing

```bash
curl -fsS -X POST \
  https://blueprintr.io/api/v1/docs/handbook/page/$PAGE_ID/publish \
  -H "Authorization: Bearer $BLUEPRINTR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"published": true}'
```

REST publishes and retracts. Its MCP twin, `update_folium_page`, accepts
`status:"draft"` only: it can retract, never publish.

A personal REST key is a human's own credential, minted behind step-up on a
password-backed account and usually driven by a CLI that human just ran. An
autonomous agent should not be what makes a draft world-readable.

`POST /versions` answers **202 Accepted** with `status:"submitted-for-review"`
when the folium requires publish approval and you are not a documentation
admin. A change request was filed, so treat it as a success.

## Deleting

`DELETE` is a **soft archive of the whole subtree**, not a hard delete. When the
page has children, the first attempt is refused and tells you how many:

```bash
curl -fsS -X DELETE \
  "https://blueprintr.io/api/v1/docs/handbook/page/$PAGE_ID?confirmSubtree=1" \
  -H "Authorization: Bearer $BLUEPRINTR_TOKEN"
```

Without `?confirmSubtree=1` a one-page delete can never take a section with it.

There is no delete tool on the MCP server at all. Deletion is offered here
because a personal key is a human's own credential and a docs CLI cannot push
one without it.

## Concurrent writes

Every write accepts `baseUpdatedAt`: the folium's `updatedAt` as you last read
it. Send it and a write that would land on top of someone else's is refused
with **409**. Omit it and the write is last-writer-wins.

`PATCH`, `POST /publish` and `POST /move` take it in the JSON body. `DELETE`
has no body, so it takes it as a query parameter:

```
DELETE /api/v1/docs/handbook/page/{id}?baseUpdatedAt=2026-09-05T23:04:11.882Z
```

Responses include both `updatedAt` (the page) and `foliumUpdatedAt` (the
document). Feed the latter back into your next write.

## Page bodies in bulk

Page bodies are served through the
[MCP server](/foliums/blueprintr-user-guide/developers/mcp-server) rather than one REST
call per page, because MCP accepts many tool calls per HTTP request. A
two-hundred-page folium is ten round trips instead of two hundred.

Both surfaces return the author's markdown **verbatim**, and neither applies
the anonymous audience filter, so a read, edit and write round trip cannot drop
an audience-gated block.

## Errors

Standard status codes, and two conventions particular to this API.

| Code | Means |
| --- | --- |
| `403` | The key kind is wrong: an org key on a personal-key route |
| `404` | Not found, **or** found and not yours. Telling you which would itself be a disclosure |
| `409` | `baseUpdatedAt` is stale. Re-read, reapply, retry |
| `202` | Accepted but not done: a version publish went to review instead |

## The CLI does all of this

[`blueprintr-docs`](/foliums/blueprintr-user-guide/foliums/docs-cli) is built on these
routes, validates offline against the server's own rules first, and refuses to
delete anything. For authoring documentation from a text editor, use it rather
than writing a client.

---

# Blueprintr User Guide: MCP server
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/developers/mcp-server

> Connect Claude Code, Codex, Cursor or any MCP client to your Blueprintr account, with the config for each.

Blueprintr exposes a personal MCP server, so an agent can read and author your
content directly.

![blueprint:josh/connecting-an-ai-agent](https://blueprintr.io/embed/josh/connecting-an-ai-agent?exclude=cmtpw8vmp002alduyez4fwryw&hideTabBar=1#h=620)

```http
POST https://blueprintr.io/api/mcp
Authorization: Bearer bpk_user_…
Content-Type: application/json
```

Streamable HTTP, JSON-RPC 2.0, **POST only**. There is no server→client SSE
stream, so a `GET` returns `405` with a message saying so. That is expected,
not a misconfiguration. Every response comes back inline in the POST body, so
clients that cannot open the optional stream still work. CORS is open, because
agents call cross-origin.

## Before you start

Mint a personal key at **Dashboard → Settings → API keys & MCP**. Keep the
default read scopes for a first connection; add a write scope only once you
know what the agent needs. See
[API keys and scopes](/foliums/blueprintr-user-guide/developers/api-keys-and-scopes).

## Claude Code

```bash
claude mcp add --transport http blueprintr https://blueprintr.io/api/mcp \
  --header "Authorization: Bearer $BLUEPRINTR_API_KEY"
```

Then run `/mcp` and confirm `blueprintr` is connected.

To share the server with a project instead, commit a `.mcp.json` that reads the
key from the environment rather than one with the key in it:

```json
{
  "mcpServers": {
    "blueprintr": {
      "type": "http",
      "url": "https://blueprintr.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${BLUEPRINTR_API_KEY}"
      }
    }
  }
}
```

Export `BLUEPRINTR_API_KEY` before starting Claude Code.

## Codex

Codex reads the token from an environment variable rather than storing it:

```bash
export BLUEPRINTR_API_KEY='bpk_user_…'
codex mcp add blueprintr \
  --url https://blueprintr.io/api/mcp \
  --bearer-token-env-var BLUEPRINTR_API_KEY
codex mcp list
```

The variable has to be present whenever Codex starts, so put the export in your
shell profile or a direnv file rather than typing it each session.

## Cursor

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "blueprintr": {
      "url": "https://blueprintr.io/api/mcp",
      "headers": {
        "Authorization": "Bearer bpk_user_…"
      }
    }
  }
}
```

Restart Cursor, then check **Settings → Tools & MCP**. A project-level file with
a key in it must not be committed.

## VS Code with Copilot

`.vscode/mcp.json`. This form prompts for the key instead of storing it, which
makes the file safe to commit:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "blueprintr-key",
      "description": "Blueprintr personal API key",
      "password": true
    }
  ],
  "servers": {
    "blueprintr": {
      "type": "http",
      "url": "https://blueprintr.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:blueprintr-key}"
      }
    }
  }
}
```

Run **MCP: List Servers** from the command palette, start `blueprintr`, then use
it from Copilot's agent mode.

## Claude Desktop

Not yet. Its remote-connector UI accepts authless or OAuth servers, and
Blueprintr's personal keys are a static bearer header. `claude_desktop_config.json`
is for local stdio servers, so the remote endpoint does not belong there either.

Use Claude Code, Codex, Cursor or VS Code until Blueprintr offers OAuth for
personal MCP connections.

## Any other client

Most clients have a generic remote-server form. These are the values:

| Field | Value |
| --- | --- |
| Name | `blueprintr` |
| Transport | Streamable HTTP |
| URL | `https://blueprintr.io/api/mcp` |
| Header name | `Authorization` |
| Header value | `Bearer bpk_user_…` |

## First calls

Ask the agent for these in order. Each one fails in a different, informative
way if the key is wrong:

```text
Use Blueprintr's whoami tool.
List my draft blueprints.
Search my content for "payments".
```

`whoami` works with any live key and reports the scopes it has, so a key minted
with the wrong ones shows up on the first call. If the client lists only
`whoami`, the key has no other scope. If it lists the *documentation* tools
instead, the key was not accepted at all.

## What it will not do

> [!IMPORTANT]
> There are no tools for deleting or trashing content, changing sharing
> permissions, or reaching account, billing, security or admin settings. The
> server cannot grant another person access to anything. Visibility moves only
> through the constrained publish and audience tools. Those are monotonic:
> they can narrow an audience, never widen it.

Blueprint writes affect your own drafts only. Published, team-authored and
org-authored blueprints are edited in the app.

## A second server: your documentation

Everything above is the **account** server: your content, authenticated as
you. A folium also publishes its own read-only MCP server, so an agent can
search and read *that documentation* with no key at all:

```
https://docs.example.com/foliums/<slug>/mcp
```

**Manage → MCP server** on any folium gives you the URL and a ready-made
snippet for Claude Code, Cursor and VS Code. The Claude Code one is a single
line, with no header:

```bash
claude mcp add --transport http my-docs https://docs.example.com/foliums/<slug>/mcp
```

| | Account server | Documentation server |
| --- | --- | --- |
| URL | `/api/mcp` | `/foliums/<slug>/mcp` |
| Auth | Personal key, required | None, for public content |
| Reads | Everything you can see | One folium |
| Writes | With a write scope | Never |

Point a customer's agent at the documentation server and your own at the
account server. An organisation key with the `mcp` scope widens the
documentation server to that organisation's private docs.

## Where to go next

> [!TILES 2]
>
> === [Tool reference](/foliums/blueprintr-user-guide/developers/mcp-tool-reference)
>
> All 72 tools, the scope each needs, and the limits that apply.
>
> === [Documentation CLI](/foliums/blueprintr-user-guide/foliums/docs-cli)
>
> For folium authoring from a text editor, use this rather than MCP.

---

# Blueprintr User Guide: Webhooks
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/developers/webhooks

> Eleven events, a signed envelope, and how to verify a delivery in constant time.

An organisation can register endpoints that receive a POST when something
happens. Managing them needs `webhook.manage`.

## Events

Subscribe to any subset. An empty selection means every event.

| Event | Fires when |
| --- | --- |
| `blueprint.published` | A blueprint goes draft → published, or a draft sibling is merged into its published parent |
| `blueprint.unpublished` | A blueprint is deprecated, set back to draft, or hard-deleted |
| `blueprint.visibility.changed` | Visibility changes via the Share dialog or the wizard |
| `folium.published` | A folium version is published: a frozen snapshot of the whole tree |
| `folium.page.updated` | A page's content or metadata is saved, in the live working set |
| `folium.page.created` | A page is added to a folium |
| `workflow.run.submitted` | An author hands a draft into an approval workflow |
| `workflow.run.approved` | The last step of a run is approved |
| `workflow.run.rejected` | An approver rejects at any step |
| `member.added` | Someone joins the org, by invite or direct add |
| `member.removed` | Someone is removed, or leaves |

## The request

```http
POST https://your-endpoint.example.com/blueprintr
Content-Type: application/json
User-Agent: Blueprintr-Webhooks/1
X-Blueprintr-Event: folium.page.updated
X-Blueprintr-Delivery: cmtp0q7uv0002mohxnqod3vkb
X-Blueprintr-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015…
```

```json
{
  "id": "cmtp0q7uv0002mohxnqod3vkb",
  "event": "folium.page.updated",
  "orgId": "cmrdzv7ts0001fnywvijnxgaz",
  "occurredAt": "2026-09-05T23:04:11.882Z",
  "payload": { }
}
```

`id` is the delivery id and doubles as your dedupe key. It is also in the
`X-Blueprintr-Delivery` header, so you can dedupe before parsing the body.

## Verifying

`X-Blueprintr-Signature` is `sha256=` followed by the hex HMAC-SHA256 of the
**exact bytes of the request body**, keyed with the endpoint's secret. Read
the raw body. A framework that parses and re-serialises JSON for you will
change key order or whitespace, and every signature will fail.

```js
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}
```

Compare in constant time. A plain `===` leaks the correct signature one byte at
a time to anyone who can measure your response latency.

> [!IMPORTANT]
> An unverified endpoint is an unauthenticated write path into whatever it
> triggers. Verify on every request and reject what fails. Do not log and
> continue.

## Provider shapes

An endpoint has a provider mode, and it changes the body on the wire:

| Provider | Body |
| --- | --- |
| `generic` | The envelope above |
| `slack` | A Slack incoming-webhook payload: `{ text, blocks }` |
| `discord` | A Discord webhook payload: `{ content, embeds }` |
| `msteams` | A Teams MessageCard |

The signature is computed over what is sent, so a Slack-shaped delivery is
signed over the Slack JSON, not over the envelope. Point a `slack`
endpoint at a Slack incoming-webhook URL and it works with no receiver of your
own.

## Endpoint requirements

The URL must be HTTPS on a public host. Private, link-local and metadata
addresses are refused, and the connection is pinned to the address that was
validated, so a hostname that resolves to something public during the check and
to something internal a moment later still cannot be reached.

| | |
| --- | ---: |
| Request timeout | 5 seconds |
| Response body read | first 1 KB, then discarded |

Return a 2xx quickly and do the work afterwards. A slow endpoint is a failed
delivery.

## There are no retries

> [!IMPORTANT]
> A failed delivery is recorded and **not** retried. There is no backoff and no
> redelivery queue, so if your endpoint was down, that event is gone.

Treat webhooks as a low-latency hint that something changed, and reconcile
against the [REST API](/foliums/blueprintr-user-guide/developers/rest-api) for
anything you cannot afford to miss. Ordering is not guaranteed either, so make
handlers idempotent on `id`.

Every attempt, succeeded or failed, is recorded with its response status and
error.

## Testing

**Send test** on the webhook posts a real signed delivery to the endpoint and
records the result in the same log. Use it to prove the signature check before
subscribing.

## Rotating a secret

Rotation is a **hard cutover**. The new secret signs the next delivery, and
every receiver still verifying with the old one starts failing immediately.

> [!STEPS]
>
> === Teach the receiver both secrets
>
> Deploy it accepting either the current secret or an as-yet-unset second one,
> before you rotate.
>
> === Rotate
>
> From the webhook's settings. You will be asked to reauthenticate: rotation
> hands out a live signing secret and breaks every receiver, so a stolen
> session cannot do it alone. Limited to five rotations an hour.
>
> === Drop the old secret
>
> Once a delivery has verified against the new one.

---

# Blueprintr User Guide: MCP tool reference
URL: https://docs.blueprintr.io/foliums/blueprintr-user-guide/developers/mcp-tool-reference

> All 72 account tools, the scope each one needs, the payload ceilings and the common errors.


`tools/list` returns **only** the tools the presented key's scopes allow. A
key with no write scope cannot see a write tool, let alone call one.

Full argument schemas come back from `tools/list` itself.

## Tools by scope

### No scope required

| Tool | What it does |
| --- | --- |
| `whoami` | Return the identity this API key acts as: your username, display name, plan, and the scopes granted to this key |

### `read:blueprints`

| Tool | What it does |
| --- | --- |
| `get_blueprint` | Fetch one of your blueprints by id or slug: prose files plus every diagram tab's components |
| `get_blueprint_analytics` | Aggregate reach for one blueprint you can edit: human views, unique visitors, traffic-source and referrer breakdowns, crawler/AI-agent traffic, and the helpful/not-helpful tally |
| `get_blueprint_audience` | Report who can currently reach a blueprint you can edit: its visibility, its classification label, and whether a password gate is set |
| `get_blueprint_translation` | Fetch one locale's translation: the translated title and summary, plus the per-stratum name/body overlays |
| `get_portfolio` | Fetch one portfolio by id: its metadata, folder tree, and everything filed in it |
| `get_review_status` | Where a blueprint stands in its team's approval gate, and whether `submit_for_review` would be accepted right now |
| `get_standalone_diagram` | Fetch one standalone diagram in full, including its body |
| `get_stratum` | Fetch one stratum by id: its body plus every secondary tab |
| `get_template` | Fetch one template's metadata and shape: name, description, category, scope, and counts of what the snapshot contains |
| `list_blueprint_locales` | List the languages a blueprint publishes in, with how much of each translation exists |
| `list_blueprint_tags` | List a blueprint's tags, with how each was attached (manual / llm-accepted) and its taxonomy placement |
| `list_blueprints` | List your blueprints, owned and shared with you |
| `list_change_requests` | List the change requests filed against a blueprint you can edit |
| `list_diagram_tabs` | List a blueprint's diagram tabs and the components on each, with ids, kinds and body sizes |
| `list_icon_packs` | List the icon libraries available to you: curated packs, your own uploads, and packs shared by your teams |
| `list_podium_slides` | List every Podium slide on a blueprint, grouped by chapter, with id, label and geometry |
| `list_portfolios` | List your portfolios, with item counts |
| `list_standalone_diagrams` | List standalone diagrams owned by you or by a team/org you belong to |
| `list_strata` | List the strata on a blueprint you can view |
| `list_templates` | List Compendium templates you can see: personal, shared, and Blueprintr defaults |

### `read:vellums`

| Tool | What it does |
| --- | --- |
| `get_vellum` | Fetch one vellum diagram in full, including its `docYaml` body |
| `list_vellums` | List your vellum diagrams: owned, shared via team/org, or granted to you |

### `read:foliums`

| Tool | What it does |
| --- | --- |
| `get_folium` | Fetch one folium: metadata, the full page tree (ids, titles, slugs, resolved URL paths, draft status, body sizes) and its strata index |
| `get_folium_page` | Fetch one folium page in full, including its markdown body |
| `get_folium_stratum` | Fetch one folium-owned stratum in full |
| `list_foliums` | List the foliums you can author, newest-edited first |

### `read:organization`

| Tool | What it does |
| --- | --- |
| `get_org` | Fetch one organisation you belong to, with your role, aggregate counts and your teams inside it |
| `get_team` | Fetch one team by id or slug. Pair a slug with `orgId` when two of your orgs use the same one |
| `list_orgs` | List the organisations you belong to, with your role in each |
| `list_teams` | List the teams you belong to, with your role and the organisation each sits under |

### `search`

| Tool | What it does |
| --- | --- |
| `search_my_content` | Full-text search across the blueprints and docs you can access |

### `write:blueprints`

| Tool | What it does |
| --- | --- |
| `create_blueprint` | Create a new blueprint as a private draft |
| `create_blueprint_from_template` | Create a private draft from a blueprint template you can see |
| `create_diagram_tab` | Add a diagram tab to a blueprint, carrying one component |
| `create_portfolio` | Create a portfolio in a workspace you administer |
| `create_portfolio_folder` | Create a folder inside a portfolio you manage |
| `create_standalone_diagram` | Create a standalone diagram you own |
| `create_stratum` | Add a stratum, optionally bound to a diagram shape so it opens when that shape is clicked |
| `create_stratum_tab` | Add a secondary tab to a stratum |
| `create_template_from_blueprint` | Capture a blueprint as a reusable personal template |
| `file_blueprint` | File a blueprint into a portfolio you manage |
| `publish_blueprint` | Publish one of your standalone draft blueprints |
| `rename_podium_slide` | Change the label of one Podium slide, leaving every other slide untouched |
| `save_blueprint_translation` | Upsert one locale's translation of a blueprint you can edit |
| `set_blueprint_tags` | Replace the whole tag set on a blueprint |
| `unfile_blueprint` | Return a blueprint to its owner's Main portfolio |
| `update_blueprint` | Update one of your **draft** blueprints: title, summary, and/or body |
| `update_diagram_component` | Replace a diagram component's source (diagram YAML/XML, or markdown for a rich component) |
| `update_portfolio` | Rename a portfolio, or change its description |
| `update_standalone_diagram` | Update a standalone diagram's title and/or body |
| `update_stratum` | Update a stratum's name and/or body |
| `update_stratum_tab` | Update a secondary tab's name and/or body |
| `update_template_details` | Rename a template, or change its description or category |

### `write:vellums`

| Tool | What it does |
| --- | --- |
| `create_template_from_vellum` | Capture a vellum as a reusable personal template |
| `create_vellum` | Create a vellum diagram from a `docYaml` body |
| `create_vellum_from_template` | Create a private vellum from a template you can see |
| `file_vellum` | File a vellum into a portfolio you manage |
| `unfile_vellum` | Return a vellum to the Unfiled bucket |
| `update_vellum` | Update a vellum's title, `docYaml` body, visibility and/or tags |

### `write:foliums`

| Tool | What it does |
| --- | --- |
| `create_folium` | Create a folium with a seed Overview page |
| `create_folium_page` | Add a page to a folium's nav tree |
| `create_folium_stratum` | Add a folium-owned stratum, which is what a `stratum:` link inside a folium page opens |
| `move_folium_page` | Reparent and/or reorder one page in the nav tree |
| `update_folium` | Update a folium's title and/or description |
| `update_folium_page` | Update a page's title, description, body, icon or nav placement |
| `update_folium_stratum` | Update a folium stratum's name, body, language hint, icon or folder path |

### `write:sharing`

| Tool | What it does |
| --- | --- |
| `raise_blueprint_classification` | Raise the classification label: public → internal → confidential |
| `restrict_blueprint_audience` | Make a blueprint less visible: public → unlisted → private |

### `write:review`

| Tool | What it does |
| --- | --- |
| `create_change_request` | File a change request against a blueprint you can edit |
| `submit_for_review` | Hand a team-owned draft into its team's approval gate |
| `withdraw_change_request` | Retract an open change request you authored |

## Calling a tool directly

The transport is plain JSON-RPC, so you can test without a client:

```bash
curl -fsS https://blueprintr.io/api/mcp \
  -H "Authorization: Bearer $BLUEPRINTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_blueprints",
                 "arguments":{"status":"draft","limit":10}}}' \
  | jq -r '.result.content[0].text | fromjson'
```

List tools return a `nextCursor`. Pass it back as `cursor` for the next page
rather than raising `limit`: the ceiling is 100, and paging is cheaper than a
retry.

Up to 20 JSON-RPC messages can go in one batch array. Past that the request is
rejected: a single HTTP request clears the rate limiter once, so an uncapped
batch would fan one request out into arbitrarily many tool calls.

## Concurrent writes

`update_vellum` accepts a `baseUpdatedAt`. Send the `updatedAt` you read, and
the write is refused with `STALE_WRITE` if the document moved underneath you.
Re-read, reapply, retry with the new timestamp.

Without it, the write is last-writer-wins. On a document a person also has
open, send it.

## Payload ceilings

| Field | Limit |
| --- | ---: |
| Blueprint title | 500 characters |
| Blueprint summary | 280 characters |
| Blueprint body | 256 KiB |
| Vellum `docYaml` | 1,500,000 characters |
| Vellum title | 200 characters |
| Vellum tags | 20 tags, 1–64 characters each |

## Rate limits

Every window is five minutes.

| Bucket | Limit |
| --- | ---: |
| Requests per IP | 60 |
| Requests per key | 600 |
| Write tool calls per key | 40 |
| JSON-RPC messages per batch | 20 |

Request-level limits return HTTP `429` and JSON-RPC `-32000`. The write bucket
returns a tool error asking you to slow down, so it arrives as a normal
result with `isError: true` rather than as a transport failure.

## Errors

| Symptom | What it means |
| --- | --- |
| Only `whoami` is listed | The key has no other scope. Scopes are fixed at creation, so mint a new key |
| The *documentation* tools are listed | The key was not accepted at all. Check the header is complete, and that the key is not revoked |
| `405` on `GET` | Expected. The optional SSE stream is not enabled; use `POST` |
| "Blueprint not found" | Wrong id, or not reachable by this account. Missing and forbidden return the same message, because telling you which would itself be a disclosure |
| A published blueprint will not update | Writes reach your own drafts only |
| `STALE_WRITE` | Someone else changed the vellum. Re-read and retry |
| A vellum body write is refused | Blueprint-bound vellums are edited through the blueprint; a standalone one needs live collaboration switched off first |
| `429` or `-32000` | Poll less, batch smaller |

Tool failures come back as MCP results with `isError: true` and a readable
message. Only protocol failures use the JSON-RPC `error` object, so a client
that checks only for `error` will read a refused write as a success.