Common data model

Printer related

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 related

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 related

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.

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.

Print History

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

Print Statistics

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