.. _sec-api-push: ************ Push updates ************ .. warning:: The interface documented here is the status quo that might be changed while the interfaces are streamlined for a more general consumption. If you happen to want to develop against it, you should drop me an email to make sure I can give you a heads-up when something changes. .. contents:: To enable real time information exchange between client and server, OctoPrint uses `SockJS `_ to push status updates, temperature changes etc to connected web interface instances. Each pushed message consists of a simple JSON object that follows this basic structure: .. sourcecode:: javascript { "": } ``type`` indicates the type of message being pushed to the client, the attached ``payload`` is message specific. The following message types are currently available for usage by 3rd party clients: * ``connected``: Initial connection information, sent only right after establishing the socket connection. See :ref:`the payload data model `. * ``reauthRequired``: A reauthentication of the current login session is required. The ``reason`` parameter in the payload defines whether a full active login is necessary (values ``logout``, ``stale``, ``removed``) or a simple passive login will suffice (all other values). * ``current``: Rate limited general state update, payload contains information about the printer's state, job progress, accumulated temperature points and log lines since last update. OctoPrint will send these updates when new information is available, but not more often than twice per second in order to not flood the client with messages (e.g. during printing). See :ref:`the payload data model `. * ``history``: Current state, temperature and log history, sent upon initial connect to get the client up to date. Same payload data model as ``current``, see :ref:`the payload data model `. * ``event``: Events triggered within OctoPrint, such as e.g. ``PrintFailed`` or ``MovieRenderDone``. Payload is the event type and payload, see :ref:`the payload data model `. Sent when an event is triggered internally. * ``slicingProgress``: Progress updates from an active slicing background job, payload contains information about the model being sliced, the target file, the slicer being used and the progress as a percentage. See :ref:`the payload data model `. * ``plugin``: Messages generated by plugins. The payload data models are determined by the plugin which sent the message. Clients must ignore any unknown messages. The data model of the attached payloads is described further below. OctoPrint's SockJS socket also accepts three commands from the client to the server. * ``subscribe`` (since 1.8.0): With the ``subscribe`` message, clients may selectively subscribe to certain message types. The payload should be a dict of message types with supported keys as follows: * ``state``: Either a boolean value indicating whether to generally receive state updates (``current`` and ``history``) or not, or a dict with further options for received state updates. Currently the following options are recognized here: * ``logs``: A boolean value whether to include all log lines (``True``, default) or not (``False``). Alternatively a string with a regex pattern can be provided, in which case only log lines matching the pattern will be returned. * ``messages``: Like ``logs`` but for the returned message lines. * ``plugins``: Either a boolean value indicating whether to generally receive plugin messages, or a list of plugin identifiers to receive plugin messages for. * ``events``: Either a boolean value indicating whether to generally receive event messages, or a list of event types to receive event messages for. If you send a ``subscribe`` message, OctoPrint will default the connection to not subscribe you to anything you did't explicitly request. ``subscribe`` messages do replace previous ones. Example for a ``subscribe`` message subscribing only to updates from plugin ``example`` but neither state nor events: .. sourcecode:: javascript { "subscribe": { "plugins": ["example"] } } Example for a ``subscribe`` message subscribing to state, event and plugin updates, but filtering logs in state updates to only contain lines matching ``^Recv: Cap`` and also filtering out all messages: .. sourcecode:: javascript { "subscribe": { "state": { "logs": "^Recv: Cap", "messages": false }, "events": true, "plugins": true } } Example for a ``subscribe`` message subscribing only to events of type ``PrintFailed``: .. sourcecode:: javascript { "subscribe": { "events": ["PrintFailed"] } } .. note:: Per default, OctoPrint will subscribe connecting clients to all state, event and plugin updates without any filtering in place. If you wish to have your more selective subscription active right from the start of your socket session, be sure to send the ``subscribe`` message **before** the ``auth`` message. * ``auth`` (since 1.3.10): With the ``auth`` message, clients may associate an existing user session with the socket. That is of special importance to receive any kind of messages, since the permission system will prevent any kind of status messages to be sent to connected clients lacking the ``STATUS`` permission. The ``auth`` message expects the user id of the user to authenticate followed by ``:`` and a session key to be obtained from the successful payload of a :ref:`(passive or active) login via the API `. Example for a ``auth`` client-server-message: .. sourcecode:: javascript { "auth": "someuser:LGZ0trf8By" } An example for an auth roundtrip with only an API key using the :ref:`JS Client Library ` can be found :ref:`here `. .. mermaid:: sequenceDiagram participant Client participant API participant Websocket Client->>API: GET /api/login?passive=true&apikey=... API->>Client: { name: ..., session: ..., ... } note over Client: auth = name ":" session Client->>Websocket: { "auth": auth } * ``throttle``: Usually, OctoPrint will push the general state update in the ``current`` message twice per second. For some clients that might still be too fast, so they can signal a different factor to OctoPrint utilizing the ``throttle`` message. OctoPrint expects a single integer here which represents the multiplier for the base rate limit of one message every 500ms. A value of 1 hence will produce the default behaviour of getting every update. A value of 2 will set the rate limit to maximally one message every 1s, 3 to maximally one message every 1.5s and so on. Example for a ``throttle`` client-server-message: .. sourcecode:: javascript { "throttle": 2 } .. _sec-api-push-datamodel: Data model ========== .. _sec-api-push-datamodel-connected: ``connected`` payload --------------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``apikey`` - 1 - String - Current UI API KEY. The UI API KEY is a special API key that gets regenerated on every server restart and has no rights attached other than accessing the REST API. An additional browser session is needed to send valid requests when the UI API KEY is used. * - ``version`` - 1 - String - The server's version. * - ``branch`` - 1 - String - The source code branch from which the server was built. * - ``display_version`` - 1 - String - The server's version and branch in a human readable format. * - ``plugin_hash`` - 1 - String - A hash of all installed plugins. This allows to detect if there have been plugin changes between server restarts. * - ``config_hash`` - 1 - String - A hash of the currently active config. This allows to detect if there have been configuration changes between server restarts. .. _sec-api-push-datamodel-currentandhistory: ``current`` and ``history`` payload ----------------------------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``state`` - 1 - :ref:`State information ` - Information about the current machine state * - ``job`` - 1 - :ref:`Job information ` - Information about the currently active print job * - ``progress`` - 1 - :ref:`Progress information ` - Information about the current print/streaming progress * - ``currentZ`` - 1 - Float - Current height of the Z-Axis (= current height of model) during printing from a local file * - ``offsets`` - 0..1 - :ref:`Temperature offsets ` - Currently configured temperature offsets * - ``temps`` - 0..* - List of :ref:`Temperature Data Points ` - Temperature data points for plotting * - ``logs`` - 0..* - List of String - Lines for the serial communication log (send/receive) * - ``messages`` - 0..* - List of String - Lines for the serial communication log (special messages) * - ``resends`` - 1 - :ref:`Resend stats ` - Current resend statistics for the connection * - ``plugins`` - 0..1 - Map of plugin identifiers to additional data - Additional data injected by plugins via the :ref:`octoprint.printer.additional_state_data hook `, indexed by plugin identifier. Structure of additional data is determined by the plugin. .. _sec-api-push-datamodel-event: ``event`` payload ----------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``type`` - 1 - String - Name of the event * - ``payload`` - 1 - Object - Payload associated with the event .. _sec-api-push-datamodel-slicingprogress: ``slicingProgress`` payload --------------------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``slicer`` - 1 - String - Name of the slicer used * - ``source_location`` - 1 - String - Location of the source file being sliced, at the moment either ``local`` or ``sdcard`` * - ``source_path`` - 1 - String - Path of the source file being sliced (e.g. an STL file) * - ``dest_location`` - 1 - String - Location of the destination file being created, at the moment either ``local`` or ``sdcard`` * - ``dest_path`` - 1 - String - Path of the destination file being sliced (e.g. a GCODE file) * - ``progress`` - 1 - Number (Float) - Percentage of slicing job already completed