Connections

Registers a connection, or sends its heartbeat.

Agents call this when they start and every 5 minutes. instanceId is the agent's own stable id for one printer (a UUID it stores locally), so a bridge watching three printers registers three connections. Each call replaces kind, displayName, agentVersion and printerId: send the printer the user chose at pairing every time, because leaving it out unbinds the connection. The response's latestAgentVersion and updateAvailable tell the agent when a newer release of it is out, so it never has to ask anyone else.

An agent can also report its health with each heartbeat (printlog-bridge#37): mode, klipperVersion, moonrakerVersion, printerModel, outboxDepth, outboxOldestAgeSeconds, lastError (scrubbed of host names, IP addresses, file names and keys by the agent), lastErrorAt, errorCount (since its previous heartbeat), snapshots and slicerSettings. All are optional and replaced on every call; a value too long is cut and a negative number counts as 0, so health never fails the heartbeat.

put/api/Connections/{instanceId}

Request

  • Base URL: https://api.3dprintlog.com
  • URL: https://api.3dprintlog.com/api/Connections/{instanceId}
  • Auth: one of:
    • OAuth 2 (authorization code, authorization URL https://3dprintlog.auth0.com/authorize, token URL https://3dprintlog.auth0.com/oauth/token)
    • API key in header X-Api-Key
    • API key in query parameter api_key

Path parameters

instanceIdstring required

The agent's own stable id for the printer, at most 100 characters.

Request body

kindstring nullable

The connector type, e.g. moonraker. Stored lower-case.

displayNamestring nullable

The name shown on prints it logs: "Logged automatically by …".

agentVersionstring nullable
printerIdinteger nullable

The printer the user chose at pairing. Must be one of yours.

modestring nullable

How the agent reaches the printer: local or remote. At most 20 characters.

klipperVersionstring nullable

Klipper's version, at most 50 characters.

moonrakerVersionstring nullable

Moonraker's version, at most 50 characters.

printerModelstring nullable

The printer model the slicer wrote in the last job's file. At most 100 characters.

outboxDepthinteger nullable

Events and pictures waiting in the agent's outbox to be sent.

outboxOldestAgeSecondsinteger nullable

How long the oldest of them has waited, in seconds.

lastErrorstring nullable

The last warning or error the agent logged for this printer, at most 500 characters. The agent removes host names, IP addresses, file names and keys before sending it.

lastErrorAtstring date-time nullable

When it was logged. A time in the future is taken as now.

errorCountinteger nullable

Warnings and errors logged since the agent's previous heartbeat that got through.

snapshotsboolean nullable

Whether a webcam frame is added to each print.

slicerSettingsboolean nullable

Whether each print's slicer settings are sent.

Response

The connection existed and was refreshed.

idstring uuid
kindstring nullable

The connector type, lower-case: moonraker, octoprint.

instanceIdstring nullable

The agent's own stable id for this printer.

displayNamestring nullable
agentVersionstring nullable
latestAgentVersionstring nullable

The newest release of this connection's agent (printlog-bridge for moonraker), as X.Y.Z, or null when 3D Print Log doesn't know it. Read from the agent's GitHub tags every few hours, so agents learn of an update from their check-in and never call GitHub.

updateAvailableboolean

Whether PrintLogApi.Models.DTOs.Connection.ConnectionDto.AgentVersion is older than PrintLogApi.Models.DTOs.Connection.ConnectionDto.LatestAgentVersion.

printerIdinteger nullable

The printer this connection logs prints for, or null when it is not bound to one.

createdDatestring date-time
lastSeenAtstring date-time

When the agent last sent a heartbeat.

status1 | 2

Whether a connection's agent is still sending heartbeats.

Sent as an integer: 1 = Online, 2 = Stale.

droppedNotifierEventCountinteger

Moonraker notifier events dropped because this connection logs the same printer. Each job is logged once, by the connection.

lastDroppedNotifierEventAtstring date-time nullable

When a notifier event was last dropped.

notifierNoticeDismissedAtstring date-time nullable

When you dismissed the notice about the notifier.

showNotifierNoticeboolean

Whether to suggest removing the [notifier] section from moonraker.conf: events were dropped and the notice has not been dismissed.

modestring nullable

How the agent reaches the printer: local or remote.

klipperVersionstring nullable
moonrakerVersionstring nullable
printerModelstring nullable

The printer model the slicer wrote in the last job's file.

outboxDepthinteger nullable

Events and pictures waiting in the agent's outbox to be sent.

outboxOldestQueuedAtstring date-time nullable

When the oldest of them was queued.

lastErrorstring nullable

The last warning or error the agent logged for this printer.

lastErrorAtstring date-time nullable

When it was logged.

errorCountinteger nullable

Warnings and errors logged between the agent's last two heartbeats.

snapshotsboolean nullable

Whether a webcam frame is added to each print.

slicerSettingsboolean nullable

Whether each print's slicer settings are sent.

Changes

No recorded changes to this operation across all 1 revision of this API.