Common data model

Printer State

Name

Multiplicity

Type

Description

text

1

String

A textual representation of the current state of the printer, e.g. “Operational” or “Printing”

flags

1

Printer state flags

A few boolean printer state flags

flags.operational

1

Boolean

true if the printer is operational, false otherwise

flags.paused

1

Boolean

true if the printer is currently paused, false otherwise

flags.printing

1

Boolean

true if the printer is currently printing, false otherwise

flags.pausing

1

Boolean

true if the printer is currently printing and in the process of pausing, false otherwise

flags.cancelling

1

Boolean

true if the printer is currently printing and in the process of pausing, false otherwise

flags.sdReady

1

Boolean

true if the printer’s SD card is available and initialized, false otherwise. This is redundant information to the SD State.

flags.error

1

Boolean

true if an unrecoverable error occurred, false otherwise

flags.ready

1

Boolean

true if the printer is operational and no data is currently being streamed to SD, so ready to receive instructions

flags.closedOrError

1

Boolean

true if the printer is disconnected (possibly due to an error), false otherwise

Temperature Data

Name

Multiplicity

Type

Description

actual

1

Number

Current temperature

target

1

Number

Target temperature, may be null if no target temperature is set.

offset

0..1

Number

Currently configured temperature offset to apply, will be left out for historic temperature information.

Historic Temperature Data Point

Name

Multiplicity

Type

Description

time

1

Unix Timestamp

Timestamp of this data point

tool{n}

0..*

Temperature Data

Temperature stats for tool n. Enumeration starts at 0 for the first tool. Not included if querying only bed state.

bed

0..*

Temperature Data

Temperature stats for the printer’s heated bed. Not included if querying only tool state.

Temperature offset

Name

Multiplicity

Type

Description

tool{n}

0..1

Number

Temperature offset for tool n. Enumeration starts at 0 for the first tool.

bed

0..1

Number

Temperature offset for the printer’s heated bed.

Resend stats

Name

Multiplicity

Type

Description

count

1

int

Number of resend requests received since connecting.

transmitted

1

int

Number of transmitted lines since connecting.

ratio

1

int

Percentage of resend requests vs transmitted lines. Value between 0 and 100.

Job information

Name

Multiplicity

Type

Description

file

1

File information (abridged)

The file that is the target of the current print job

estimatedPrintTime

0..1

Float

The estimated print time for the file, in seconds.

lastPrintTime

0..1

Float

The print time of the last print of the file, in seconds.

filament

0..1

Object

Information regarding the estimated filament usage of the print job

filament.length

0..1

Float

Length of filament used, in mm

filament.volume

0..1

Float

Volume of filament used, in cm³

Progress information

Name

Multiplicity

Type

Description

completion

1

Float

Percentage of completion of the current print job

filepos

1

Integer

Current position in the file being printed, in bytes from the beginning

printTime

1

Integer

Time already spent printing, in seconds

printTimeLeft

1

Integer

Estimate of time left to print, in seconds

printTimeLeftOrigin

1

String

Origin of the current time left estimate. Can currently be either of:

  • linear: based on an linear approximation of the progress in file in bytes vs time

  • analysis: based on an analysis of the file

  • estimate: calculated estimate after stabilization of linear estimation

  • average: based on the average total from past prints of the same model against the same printer profile

  • mixed-analysis: mixture of estimate and analysis

  • mixed-average: mixture of estimate and average

File information

Name

Multiplicity

Type

Description

name

1

String

The name of the file without path. E.g. “file.gco” for a file “file.gco” located anywhere in the file system. Currently this will always fit into ASCII.

display

1

String

The name of the file without the path, this time potentially with non-ASCII unicode characters. E.g. “a turtle 🐢.gco” for a file “a_turtle_turtle.gco” located anywhere in the file system.

path

1

String

The path to the file within the location. E.g. “folder/subfolder/file.gco” for a file “file.gco” located within “folder” and “subfolder” relative to the root of the location. Currently this will always fit into ASCII.

type

1

String

Type of file. model or machinecode. Or folder if it’s a folder, in which case the children node will be populated

typePath

1

list

Path to type of file in extension tree. E.g. ["model", "stl"] for .stl files, or ["machinecode", "gcode"] for .gcode files. ["folder"] for folders.

user

0..1

String

User who uploaded the file/created the folder, if this information is available.

Additional properties depend on type. For a type value of folder, see Folders. For any other value see Files.

Folders

Name

Multiplicity

Type

Description

children

0..*

Array of File information items

Contained children for entries of type folder. On non recursive listings only present on first level sub folders!

size

0..1

Number

The size of all files contained in the folder and its subfolders. Not present in non recursive listings!

Files

Name

Multiplicity

Type

Description

hash

0..1

String

MD5 hash of the file. Only available for local files.

size

0..1

Number

The size of the file in bytes. Only available for local files or sdcard files if the printer supports file sizes for sd card files.

date

0..1

Unix timestamp

The timestamp when this file was uploaded. Only available for local files.

origin

1

String, either local or sdcard

The origin of the file, local when stored in OctoPrint’s uploads folder, sdcard when stored on the printer’s SD card (if available)

refs

0..1

References

References relevant to this file, left out in abridged version

gcodeAnalysis

0..1

GCODE analysis information

Information from the analysis of the GCODE file, if available. Left out in abridged version.

prints

0..1

Print history information

Information about previous prints of the file. Left out if the file has never been printed.

statistics

0..1

Print statistics information

Statistics about the file, based on the previous print times. Left out if the file has never been printed.

Abridged file or folder information

Name

Multiplicity

Type

Description

name

1

String

The name of the file or folder without path. E.g. “file.gco” for a file “file.gco” located anywhere in the file system. Currently this will always fit into ASCII.

display

1

String

The name of the file without the path, this potentially with non-ASCII unicode characters. E.g. “a turtle 🐢.gco” for a file “a_turtle_turtle.gco” located anywhere in the file system.

path

1

String

The path to the file or folder within the location. E.g. “folder/subfolder/file.gco” for a file “file.gco” located within “folder” and “subfolder” relative to the root of the location. Currently this will always fit into ASCII.

origin

1

String, either local or sdcard

The origin of the file, local when stored in OctoPrint’s uploads folder, sdcard when stored on the printer’s SD card (if available)

refs

0..1

References

References relevant to this file or folder, left out in abridged version

GCODE analysis information

Name

Multiplicity

Type

Description

estimatedPrintTime

0..1

Float

The estimated print time of the file, in seconds

filament

0..1

Object

The estimated usage of filament

filament.tool{n}.length

0..1

Float

The length of filament used, in mm

filament.tool{n}.volume

0..1

Float

The volume of filament used, in cm³

dimensions

0..1

Object

Information regarding the size of the printed model

dimensions.depth

0..1

Float

The depth of the printed model, in mm

dimensions.height

0..1

Float

The height of the printed model, in mm

dimensions.width

0..1

Float

The width of the printed model, in mm

printingArea

0..1

Object

Information regarding the size of the printing area

printingArea.maxX

0..1

Float

The maximum X coordinate of the printed model, in mm

printingArea.maxY

0..1

Float

The maximum Y coordinate of the printed model, in mm

printingArea.maxZ

0..1

Float

The maximum Z coordinate of the printed model, in mm

printingArea.minX

0..1

Float

The minimum X coordinate of the printed model, in mm

printingArea.minY

0..1

Float

The minimum Y coordinate of the printed model, in mm

printingArea.minZ

0..1

Float

The minimum Z coordinate of the printed model, in mm

travelArea

0..1

Object

Information regarding the bounding box of all moves

travelArea.maxX

0..1

Float

The maximum X coordinate of all moves, in mm

travelArea.maxY

0..1

Float

The maximum Y coordinate of all moves, in mm

travelArea.maxZ

0..1

Float

The maximum Z coordinate of all moves, in mm

travelArea.minX

0..1

Float

The minimum X coordinate of all moves, in mm

travelArea.minY

0..1

Float

The minimum Y coordinate of all moves, in mm

travelArea.minZ

0..1

Float

The minimum Z coordinate of all moves, in mm

travelDimensions

0..1

Object

Information regarding the size of the travel area

travelDimensions.depth

0..1

Float

The depth of the travel area, in mm

travelDimensions.height

0..1

Float

The height of the travel area, in mm

travelDimensions.width

0..1

Float

The width of the travel area, in mm

References

Name

Multiplicity

Type

Description

resource

1

URL

The resource that represents the file or folder (e.g. for issuing commands to or for deleting)

download

0..1

URL

The download URL for the file. Never present for folders.

model

0..1

URL

The model from which this file was generated (e.g. an STL, currently not used). Never present for folders.

Name

Multiplicity

Type

Description

success

1

Number

Number of successful prints

failure

1

Number

Number of failed prints

last.date

1

Unix Timestamp

Last date this file was printed

last.printTime

1

Float

Last print time in seconds

last.success

1

Boolean

Whether the last print was a success or not

Name

Multiplicity

Type

Description

averagePrintTime

1

Object

Object that maps printer profile names to the last print time of the file, in seconds

lastPrintTime

1

Object

Object that maps printer profile names to the average print time of the file, in seconds

Access control

User record

Name

Multiplicity

Type

Description

name

1

string

The user’s name

active

1

bool

Whether the user’s account is active (true) or not (false)

user

1

bool

Whether the user has user rights. Should always be true. Deprecated as of 1.4.0, use the users group instead.

admin

1

bool

Whether the user has admin rights (true) or not (false). Deprecated as of 1.4.0, use the admins group instead.

apikey

0..1

string

The user’s personal API key

settings

1

object

The user’s personal settings, might be an empty object.

groups

1..n

List of string

Groups assigned to the user

needs

1

Needs object

Effective needs of the user

permissions

0..n

List of Permissions

The list of permissions assigned to the user (note: this does not include implicit permissions inherit from groups).

Permission record

Name

Multiplicity

Type

Description

key

1

string

The permission’s identifier

name

1

string

The permission’s name

dangerous

1

boolean

Whether the permission should be considered dangerous due to a high responsibility (true) or not (false).

default_groups

1

List of string

List of group identifiers for which this permission is enabled by default

description

1

string

Human readable description of the permission

needs

1

Needs object

Needs assigned to the permission

Group record

Name

Multiplicity

Type

Description

key

1

string

The group’s identifier

name

1

string

The group’s name

description

1

string

A human readable description of the group

permissions

0..n

List of Permissions

The list of permissions assigned to the group (note: this does not include implicit permissions inherited from subgroups).

subgroups

0..n

List of Groups

Subgroups assigned to the group

needs

1

Needs object

Effective needs of the group

default

1

boolean

Whether this is a default group (true) or not (false)

removable

1

boolean

Whether this group can be removed (true) or not (false)

changeable

1

boolean

Whether this group can be modified (true) or not (false)

toggleable

1

boolean

Whether this group can be assigned to users or other groups (true) or not (false)

Needs

Name

Multiplicity

Type

Description

role

0..1

List of string

List of role needs

group

0..1

List of string

List of group needs