Apply a bundle. Existing rows with the same id are updated, new ones created; nothing is ever deleted, and there is no replace mode.

POST

/api/v1/config/bundle

curl --request POST \
  --url https://example.com/api/v1/config/bundle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "analysis_schedules": [ { "at_hour": 1, "at_minute": 1, "day_of_month": 1, "day_of_week": 1, "enabled": true, "frequency": "example", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": "example", "scope_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope_kind": "example", "scope_label": "example", "tool": "example" } ], "app_settings": { "default_poll_interval_secs": 1, "meraki_polling_enabled": true }, "classification_rules": [ { "enabled": true, "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "model": "example", "priority": 1, "profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "sysdescr_regex": "example", "sysobjectid_prefix": "example", "vendor": "example" } ], "collection_template_items": [ { "collection": "example", "enabled": true, "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "metric_kind": "example", "metric_name": "example", "oid": "example", "template_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" } ], "collection_templates": [ { "description": "example", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ], "dns_checks": [ { "max_depth": 1, "name": "example", "node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "record_type": "example", "resolver_ip": "example", "resolver_port": 1, "timeout_ms": 1 } ], "event_rules": [ { "clear_pattern": "example", "enabled": true, "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "match_kind": "example", "min_count": 1, "name": "example", "node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "pattern": "example", "severity": "example", "source_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "source_kind": "example", "ttl_secs": 1, "window_secs": 1 } ], "event_sources": [ { "enabled": true, "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "kind": "example", "name": "example", "node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" } ], "exported_at": "2026-04-15T12:00:00Z", "format": "example", "forward_destinations": [ { "ca_cert": "example", "dest_kind": "example", "enabled": true, "filter": "example", "had_secret": true, "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example", "pool": "example", "rate_limit_per_sec": 1, "source_kind": "example", "target": "example", "verbatim": true } ], "node_groups": [ { "group_type": "example", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "latitude": 1, "longitude": 1, "name": "example", "parent_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "pool": "example", "sort_order": 1 } ], "nodes": [ { "address": "example", "credential_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "group_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "model": "example", "name": "example", "parent_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "pool": "example", "profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "sort_order": 1, "tags": "example", "vendor": "example" } ], "notes": [ { "code": "skipped_builtin", "count": 1, "field": "example", "table": "example" } ], "profile_collection_templates": [ { "profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "template_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" } ], "profiles": [ { "category": "example", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example", "parent_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "poll_interval_secs": 1, "vendor": "example" } ], "report_definitions": [ { "description": "example", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example", "spec": "example" } ], "report_schedules": [ { "at_hour": 1, "at_minute": 1, "day_of_month": 1, "day_of_week": 1, "definition_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "enabled": true, "frequency": "example", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" } ], "secrets": "references", "thresholds": [ { "critical": 1, "direction": "example", "dwell_samples": 1, "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "metric": "example", "scope_id": "example", "scope_level": "example", "warning": 1 } ], "url_checks": [ { "body_match": "example", "body_max_bytes": 1, "credential_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expected_status": "example", "follow_redirects": true, "json_extract": "example", "method": "example", "node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "timeout_ms": 1, "url": "example", "verify_tls": true } ], "version": 1, "yagra_version": "example" }'

Authorizations

• bearer

Parameters

Query Parameters

dry_run

boolean

Run the whole import and roll it back, returning the report it would have produced.

Request Body^required

Media typeapplication/json

A whole configuration bundle.

object

analysis_schedules

Array<object>

A recurring Troubleshoot analysis.

object

at_hour

required

integer format: int32

at_minute

required

integer format: int32

day_of_month

integer | null format: int32

day_of_week

integer | null format: int32

enabled

required

boolean

frequency

required

string

id

required

string format: uuid

params

required

scope_id

string | null format: uuid

scope_kind

required

string

scope_label

required

string

tool

required

string

app_settings

One of:

null

null

object

The deployment-wide settings the bundle carries. The retention windows are deliberately absent (module docs).

object

default_poll_interval_secs

required

integer format: int32

meraki_polling_enabled

required

boolean

classification_rules

Array<object>

A discovery classification rule.

object

enabled

required

boolean

id

required

string format: uuid

model

string | null

priority

required

integer format: int32

profile_id

required

string format: uuid

sysdescr_regex

string | null

sysobjectid_prefix

string | null

vendor

string | null

collection_template_items

Array<object>

One metric inside a collection template.

object

collection

required

string

enabled

required

boolean

id

required

string format: uuid

metric_kind

required

string

metric_name

required

string

oid

required

string

template_id

required

string format: uuid

collection_templates

Array<object>

A reusable collection template.

object

description

string | null

id

required

string format: uuid

name

required

string

dns_checks

Array<object>

A DNS monitor’s configuration (1:1 with its node).

object

max_depth

required

integer format: int32

name

required

string

node_id

required

string format: uuid

record_type

required

string

resolver_ip

string | null

resolver_port

required

integer format: int32

timeout_ms

required

integer format: int32

event_rules

Array<object>

A passive-event match rule.

object

clear_pattern

string | null

enabled

required

boolean

id

required

string format: uuid

match_kind

required

string

min_count

required

integer format: int32

name

required

string

node_id

string | null format: uuid

pattern

required

string

severity

required

string

source_id

string | null format: uuid

source_kind

string | null

ttl_secs

required

integer format: int32

window_secs

required

integer format: int32

event_sources

Array<object>

A passive-event ingest source.

object

enabled

required

boolean

id

required

string format: uuid

kind

required

string

name

required

string

node_id

string | null format: uuid

exported_at

required

When the export ran.

string format: date-time

format

required

Always yagra.config-bundle. An importer refuses anything else rather than guessing.

string

forward_destinations

Array<object>

A forwarding destination. Its optional sealed secret is not carried; a destination that had one arrives disabled.

object

ca_cert

string | null

dest_kind

required

string

enabled

required

boolean

filter

required

had_secret

Whether the source deployment had a sealed secret on this destination. Carries no secret — it is what tells the importer to arrive disabled and what tells the operator to re-enter it.

boolean

id

required

string format: uuid

name

required

string

pool

string | null

rate_limit_per_sec

integer | null format: int32

source_kind

required

string

target

required

string

verbatim

required

boolean

node_groups

Array<object>

A folder in the inventory tree.

object

group_type

required

string

id

required

string format: uuid

latitude

number | null format: double

longitude

number | null format: double

name

required

string

parent_id

string | null format: uuid

pool

string | null

sort_order

required

number format: double

nodes

Array<object>

A monitored node. credential_id is a reference only — see the module docs.

object

address

required

IPv4 or IPv6, as text.

string

credential_id

string | null format: uuid

group_id

string | null format: uuid

id

required

string format: uuid

model

string | null

name

required

string

parent_id

string | null format: uuid

pool

string | null

profile_id

string | null format: uuid

sort_order

required

number format: double

tags

required

vendor

string | null

notes

What the export left out or changed. Informational; ignored on import.

Array<object>

One note, with the table it concerns and how many rows it covers.

object

code

required

What happened.

string

Allowed values: skipped_builtin skipped_missing_reference reference_dropped secret_dropped_imported_disabled webhook_token_reset schedule_next_run_recomputed

count

required

How many rows this note covers.

integer format: int32

field

The column involved, when the note is about one (e.g. credential_id).

string | null

table

required

The table the note is about.

string

profile_collection_templates

Array<object>

A profile↔template attachment.

object

profile_id

required

string format: uuid

template_id

required

string format: uuid

profiles

Array<object>

A device profile.

object

category

required

string

id

required

string format: uuid

name

required

string

parent_id

string | null format: uuid

poll_interval_secs

integer | null format: int32

vendor

string | null

report_definitions

Array<object>

A saved report template.

object

description

string | null

id

required

string format: uuid

name

required

string

spec

required

report_schedules

Array<object>

A recurring report run.

object

at_hour

required

integer format: int32

at_minute

required

integer format: int32

day_of_month

integer | null format: int32

day_of_week

integer | null format: int32

definition_id

required

string format: uuid

enabled

required

boolean

frequency

required

string

id

required

string format: uuid

secrets

How secrets are represented. Always references — a bundle never carries one.

string

Allowed values: references

thresholds

Array<object>

A threshold rule.

object

critical

number | null format: double

direction

required

string

dwell_samples

required

integer format: int32

id

required

string format: uuid

metric

required

string

scope_id

required

string

scope_level

required

string

warning

number | null format: double

url_checks

Array<object>

A URL / HTTP endpoint monitor’s configuration (1:1 with its node).

object

body_match

The monitor’s response-body keyword rule, if it has one.

body_max_bytes

How many bytes of the response body the monitor reads.

integer format: int32

credential_id

string | null format: uuid

expected_status

required

follow_redirects

required

boolean

json_extract

The monitor’s JSON extraction rules, if it has any.

method

required

string

node_id

required

string format: uuid

timeout_ms

required

integer format: int32

url

required

string

verify_tls

required

boolean

version

required

Bundle schema version.

integer format: int32

yagra_version

required

The Yagra version that produced it.

string

Responses

200

Import report: per-table counts plus what was skipped or changed and why. With dry_run nothing was committed

Media typeapplication/json

The outcome of an import.

object

dry_run

required

True when nothing was committed: the whole import ran and was rolled back.

boolean

notes

required

What was skipped or changed, and why.

Array<object>

One note, with the table it concerns and how many rows it covers.

object

code

required

What happened.

string

Allowed values: skipped_builtin skipped_missing_reference reference_dropped secret_dropped_imported_disabled webhook_token_reset schedule_next_run_recomputed

count

required

How many rows this note covers.

integer format: int32

field

The column involved, when the note is about one (e.g. credential_id).

string | null

table

required

The table the note is about.

string

tables

required

Per-table counts, in dependency order.

Array<object>

What the import did to one table.

object

created

required

integer format: int32

skipped

required

integer format: int32

table

required

string

updated

required

integer format: int32

Example

{
  "notes": [
    {
      "code": "skipped_builtin"
    }
  ]
}

400

Not a Yagra configuration bundle, or a schema version this build cannot read

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks ManageConfig

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

413

The uploaded bundle is larger than the accepted body size

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Inventory storage is unavailable (skeleton mode)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}