Skip to main content

Guide to integrate with OctoPrint/Klipper Tunnel

Acquire user authorization to use the tunnel




  • app: Required. The name of your app.
  • printer_id: Optional. If not provided, and the user has more than 1 printers linked to his/her Obico account, the page will list all printers for the user to choose from.
  • success_redirect_url: Optional. If not provided, the page will be redirected to on successful authorization.

Redirect on success

On a successful authorization, the page will be redirect to {success_redirect_url}/?tunnel_endpoint=

Use as endpoint to connect to OctoPrint/Klipper.

This value will be designated as TUNNEL_ENDPOINT for the rest of this document.

Special HTTP status code for tunnelled API calls

  • 481: Over free tunnel monthly data cap.
  • 482: Obico for OctoPrint/Klipper is not connected to the Obico server.
  • 483: Obico for OctoPrint/Klipper is connected but timed out (30s)

Other HTTP status code

  • 401: Unauthenticated request. This can be caused by:
    • User explicitly revoked the authorization.
    • User deleted the printer in Obico.
    • User account is deleted or suspended in Obico.

Tunnel APIs

Tunnel usage API




  • total: Month-to-date usage. In bytes.
  • monthly_cap: In bytes. -1 when the cap is unlimited (for Pro users, including the free trial).
  • reset_in_seconds: Remaining time (in seconds) until the usage is reset.

Webcam snapshot API




  • snapshot: The url to fetch the most recent webcam snapshot (in JPEG). No authentication is required.

Failure prediction API




  • normalized_p: The prediction value in the range of [0,1). < 0.33: Low. 0.33 - 0.66: Medium. > 0.66: High.