Skip to content
Documentation Prelude Collector 1.0.0

Models API

Define data models, fields, and protocol mappings; test them live; and import or export model definitions through the Prelude Collector REST API.

A model is a named schema that tells the Prelude Collector what to collect and how to interpret it. After this first mention, the rest of this page refers to Prelude Collector as "the collector". Models own typed fields and per-protocol mappings — the same model can be fed by gNMI on one platform and SNMP on another, so downstream consumers see a single, vendor-neutral shape. This page covers when to call which sub-resource, common pitfalls, and a worked example that builds a model end to end. For the full endpoint schema, see the API reference.

When to use this API

  • Building a custom model. Use the model, field, and mapping endpoints together to describe a new metric or state object.
  • Iterating on mappings. The live test endpoint runs a one-shot collection against a real device so you can validate field mappings before you subscribe.
  • Promoting a model between environments. Export from staging, import into production — the JSON export carries fields and mappings.
  • Renaming or reshaping fields. Keep model edits coordinated with the consumers downstream; renames break dashboards.

Common pitfalls

  • Editing fields while subscriptions are running. Changes hot-reload but in-flight rows may temporarily fall back to the old shape. Drain critical dashboards before reshaping.
  • Mapping warnings ignored. Mapping responses can include a warnings array with non-blocking syntax notes. They are not errors, but they often flag a typo that will produce empty results.
  • Using import to update an existing model. Import always creates a new model. To update in place, edit the fields and mappings directly.
  • Forgetting to reorder. Field position drives display order in snapshots and exports. After adding fields, call the reorder endpoint to lock in the layout you want.

Worked example: create, test, and export

This flow builds a minimal interface model, tests it against a real device, and exports the result for promotion.

# 1. Create the model.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"interface","description":"Interface counters and state"}' \
  https://collector.example.com/api/v1/models
# 201 Created -> {"id":1, ...}

# 2. Add a field.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"in-octets","type":"counter64"}' \
  https://collector.example.com/api/v1/models/1/fields

# 3. Add a gNMI mapping for IOS-XR.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"protocol":"gnmi","netos":"iosxr","field_mappings":{"in-octets":"/interfaces/interface/state/counters/in-octets"}}' \
  https://collector.example.com/api/v1/models/1/mappings

# 4. Run a live test against device 1, mapping 1.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"device-id":1,"mapping-id":1}' \
  https://collector.example.com/api/v1/models/1/test

# 5. Export the finished model for staging -> prod promotion.
curl -H "Authorization: Bearer <your-api-token>" \
  https://collector.example.com/api/v1/models/1/export -o interface.json

Bruno: 04 Models / Create model, 04 Models / Add field, 04 Models / Add mapping, 04 Models / Test mapping, 04 Models / Export model

The test response includes both the parsed results (matching your field schema) and the raw-updates returned by the device, which makes it easy to spot why a mapping returns empty data.

Reference

Schemas for fields, mappings, the test request, and the import/export payload are in the Bruno collection.

See also

Filtering by: