--- title: "Registers a connection, or sends its heartbeat." method: PUT path: "/api/Connections/{instanceId}" tags: ["Connections"] --- # Registers a connection, or sends its 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` 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. ## Path parameters - `instanceId` string, required ## Request body - PrintLogApiModelsDTOsConnectionPutConnectionDto: What an agent sends when it starts and on every heartbeat. Each call replaces these fields, so send the printer binding every time: leaving it out unbinds the connection. - `kind` string, nullable: The connector type, e.g. `moonraker`. Stored lower-case. - `displayName` string, nullable: The name shown on prints it logs: "Logged automatically by …". - `agentVersion` string, nullable - `printerId` integer, nullable: The printer the user chose at pairing. Must be one of yours. - `mode` string, nullable: How the agent reaches the printer: `local` or `remote`. At most 20 characters. - `klipperVersion` string, nullable: Klipper's version, at most 50 characters. - `moonrakerVersion` string, nullable: Moonraker's version, at most 50 characters. - `printerModel` string, nullable: The printer model the slicer wrote in the last job's file. At most 100 characters. - `outboxDepth` integer, nullable: Events and pictures waiting in the agent's outbox to be sent. - `outboxOldestAgeSeconds` integer, nullable: How long the oldest of them has waited, in seconds. - `lastError` string, 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. - `lastErrorAt` string, date-time, nullable: When it was logged. A time in the future is taken as now. - `errorCount` integer, nullable: Warnings and errors logged since the agent's previous heartbeat that got through. - `snapshots` boolean, nullable: Whether a webcam frame is added to each print. - `slicerSettings` boolean, nullable: Whether each print's slicer settings are sent. ## Response `200` The connection existed and was refreshed. - PrintLogApiModelsDTOsConnectionConnectionDto: A connector attached to one of your printers. - `id` string, uuid - `kind` string, nullable: The connector type, lower-case: `moonraker`, `octoprint`. - `instanceId` string, nullable: The agent's own stable id for this printer. - `displayName` string, nullable - `agentVersion` string, nullable - `latestAgentVersion` string, 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. - `updateAvailable` boolean: Whether PrintLogApi.Models.DTOs.Connection.ConnectionDto.AgentVersion is older than PrintLogApi.Models.DTOs.Connection.ConnectionDto.LatestAgentVersion. - `printerId` integer, nullable: The printer this connection logs prints for, or null when it is not bound to one. - `createdDate` string, date-time - `lastSeenAt` string, date-time: When the agent last sent a heartbeat. - `status` 1 | 2: Whether a connection's agent is still sending heartbeats. Sent as an integer: `1` = Online, `2` = Stale. - `droppedNotifierEventCount` integer: Moonraker notifier events dropped because this connection logs the same printer. Each job is logged once, by the connection. - `lastDroppedNotifierEventAt` string, date-time, nullable: When a notifier event was last dropped. - `notifierNoticeDismissedAt` string, date-time, nullable: When you dismissed the notice about the notifier. - `showNotifierNotice` boolean: Whether to suggest removing the `[notifier]` section from moonraker.conf: events were dropped and the notice has not been dismissed. - `mode` string, nullable: How the agent reaches the printer: `local` or `remote`. - `klipperVersion` string, nullable - `moonrakerVersion` string, nullable - `printerModel` string, nullable: The printer model the slicer wrote in the last job's file. - `outboxDepth` integer, nullable: Events and pictures waiting in the agent's outbox to be sent. - `outboxOldestQueuedAt` string, date-time, nullable: When the oldest of them was queued. - `lastError` string, nullable: The last warning or error the agent logged for this printer. - `lastErrorAt` string, date-time, nullable: When it was logged. - `errorCount` integer, nullable: Warnings and errors logged between the agent's last two heartbeats. - `snapshots` boolean, nullable: Whether a webcam frame is added to each print. - `slicerSettings` boolean, nullable: Whether each print's slicer settings are sent. ## Other responses - `201`: The connection was registered. - `400`: Returned when a field is missing or too long, or the printer is not yours. - `401`: Unauthorized - `403`: Forbidden --- [API](https://skmtc.dev/3dprintlog/apis/3d-print-log-api.md) · [All operations](https://skmtc.dev/3dprintlog/apis/3d-print-log-api/llms.txt) · [OpenAPI document](https://skmtc.dev/3dprintlog/apis/3d-print-log-api/revisions/dfc3a4df4e38?raw)