Outputs API

An output is a downstream connection Prelude TE uses to publish topology changes (update and withdraw events) to a consumer. After this first mention, the rest of this page refers to Prelude TE as "the engine". NATS is the only output type available in this release. This page covers when to call the API, common mistakes, and a worked NATS onboarding flow. For the full endpoint schema, see the API reference.

When to use this API

• Wiring a new consumer. Create an output to start streaming topology changes to a downstream subscriber.
• Rotating credentials. Update nkey-seed or TLS settings without losing the output's identity or history.
• Operational toggles. Flip enabled to pause streaming for maintenance, then flip it back on without recreating the entry.
• Decommissioning. Delete the output when a consumer is retired so the engine stops attempting to connect.

Endpoints

Common pitfalls

• PUT is a full replace, not a patch. Fields omitted from the body are reset to their zero value. To toggle one option, fetch the output first, mutate the field, then PUT the whole object back.
• Confusing enabled with state. enabled is your intent (the engine should hold this connection open); state is the live connection state (disconnected, connecting, connected, error). For live state see Health, or inspect last-error on the entity itself.
• TLS misconfigurations. When use-tls is true and your NATS server uses a private CA, you must also set ca-cert-path to a file path inside the engine container, not on the client machine making the API call.
• nkey-seed in plain text. The seed is stored encrypted server-side, but it travels over the wire on create and update. Use HTTPS and treat the value as a secret. The API never returns the seed back — only its derived public key.
• Operational fields on create or update. Anything that the engine owns — state, last-error, connected-at — is ignored on input.

Worked example: wire a NATS output end to end

# 1. Create the output (disabled, for review).
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "primary-nats",
        "description": "Primary NATS bus for topology updates",
        "type": "nats",
        "connection-url": "tls://nats.example.com:4222",
        "use-tls": true,
        "ca-cert-path": "/etc/prelude-te/ca.pem",
        "nkey-seed": "SUA<seed-redacted>",
        "enabled": false
      }' \
  https://te.example.com/api/outputs
# 201 Created -> {"id":7, ...}

# 2. Enable the connection once the bus is ready.
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "primary-nats",
        "description": "Primary NATS bus for topology updates",
        "type": "nats",
        "connection-url": "tls://nats.example.com:4222",
        "use-tls": true,
        "ca-cert-path": "/etc/prelude-te/ca.pem",
        "nkey-seed": "SUA<seed-redacted>",
        "enabled": true
      }' \
  https://te.example.com/api/outputs/7

# 3. Verify it is connected.
curl -H "Authorization: Bearer $TOKEN" \
  https://te.example.com/api/outputs/7
# look for "state": "connected" and a non-empty "connected-at"

Bruno: Outputs / Create output, Outputs / Update output, Outputs / Get output

Once the output is connected, every topology change is published to a topic of the form prelude.te.topology.<domain>. See Outputs / NATS for the topic format and payload schema.

Reference

The full request shape, including the small set of TLS knobs and the authentication flavors NATS supports, lives in the Bruno collection. Run the CRUD folder against a sandbox to leave the server in its original state once you are done.

See also

• Outputs / Overview
• Outputs / NATS
• Monitoring: Health
• Monitoring: Metrics