Spoolman

https://donkie.github.io/Spoolman
Admin
Spoolman is a self-hosted 3D printer filament spool manager that provides a REST API to track,...
Tokens:17,727
Snippets:89
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Get All External Materials Response

Source: https://donkie.github.io/Spoolman

Example JSON response structure containing a list of all available external materials.

```json
[
  {
    "material": "PLA",
    "density": 1.24,
    "extruder_temp": 210,
    "bed_temp": 50
  }
]
```

--------------------------------

### GET /setting/

Source: https://donkie.github.io/Spoolman

Retrieves all settings. If a setting has not been explicitly set, the default value is returned.

```APIDOC
## GET /setting/

### Description
Get all settings, set or not. If the setting has not been set, 'value' will be the default value.

### Method
GET

### Endpoint
/setting/

### Response
#### Success Response (200)
- **property** (object) - A dictionary of settings where each key contains a value, is_set status, and type.

#### Response Example
{
  "property1": {
    "value": "string",
    "is_set": true,
    "type": "boolean"
  }
}
```

--------------------------------

### Get All Settings Response Format

Source: https://donkie.github.io/Spoolman

The structure of the JSON response when retrieving all system settings.

```json
{
  "property1": {
    "value": "string",
    "is_set": true,
    "type": "boolean"
},
  "property2": {
    "value": "string",
    "is_set": true,
    "type": "boolean"
}

}
```

--------------------------------

### GET /api/v1/info

Source: https://donkie.github.io/Spoolman

Returns general information about the Spoolman API and system configuration.

```APIDOC
## GET /api/v1/info

### Description
Return general info about the API.

### Method
GET

### Endpoint
/api/v1/info

### Response
#### Success Response (200)
- **version** (string) - API version
- **debug_mode** (boolean) - Debug mode status
- **automatic_backups** (boolean) - Automatic backups status
- **data_dir** (string) - Data directory path
- **logs_dir** (string) - Logs directory path
- **backups_dir** (string) - Backups directory path
- **db_type** (string) - Database type
- **external_db_name** (string) - External database name
- **git_commit** (string) - Git commit hash
- **build_date** (string) - Build date

#### Response Example
{
  "version": "0.7.0",
  "debug_mode": false,
  "automatic_backups": true,
  "data_dir": "/home/app/.local/share/spoolman",
  "logs_dir": "/home/app/.local/share/spoolman",
  "backups_dir": "/home/app/.local/share/spoolman/backups",
  "db_type": "sqlite",
  "external_db_name": "SpoolmanDB",
  "git_commit": "a1b2c3d",
  "build_date": "2021-01-01T00:00:00Z"
}
```

--------------------------------

### GET /material

Source: https://donkie.github.io/Spoolman

Retrieve a list of all available filament materials.

```APIDOC
## GET /material

### Description
Get a list of all filament materials.

### Method
GET

### Endpoint
/material

### Response
#### Success Response (200)
- **materials** (array) - A list of all filament materials.
```

--------------------------------

### GET /external/material

Source: https://donkie.github.io/Spoolman

Retrieve a list of all available external materials.

```APIDOC
## GET /external/material

### Description
Get all external materials.

### Method
GET

### Endpoint
/external/material

### Response
#### Success Response (200)
- **material** (string) - Material name
- **density** (number) - Material density
- **extruder_temp** (integer) - Recommended extruder temperature
- **bed_temp** (integer) - Recommended bed temperature
```

--------------------------------

### GET /location

Source: https://donkie.github.io/Spoolman

Retrieves a list of all spool locations.

```APIDOC
## GET /location

### Description
Get a list of all spool locations.

### Method
GET

### Endpoint
/location

### Response
#### Success Response (200)
- **locations** (array) - A list of all spool locations.

#### Response Example
[
  "Printer 1",
  "Printer 2",
  "Storage Shelf A"
]
```

--------------------------------

### Add Vendor Response Sample

Source: https://donkie.github.io/Spoolman

Example JSON response returned upon a successful vendor creation.

```json
{
  "id": 0,
  "registered": "string",
  "name": "Polymaker",
  "comment": "",
  "empty_spool_weight": 140,
  "external_id": "eSun",
  "extra": {
    "property1": "string",
    "property2": "string"
}

}
```

--------------------------------

### GET /lot-number

Source: https://donkie.github.io/Spoolman

Retrieve a list of all lot numbers.

```APIDOC
## GET /lot-number

### Description
Get a list of all lot numbers.

### Method
GET

### Endpoint
/lot-number

### Response
#### Success Response (200)
- **lot_numbers** (array) - A list of all lot numbers.
```

--------------------------------

### GET /search

Source: https://donkie.github.io/Spoolman

Search across spools, filaments, and vendors in a single request.

```APIDOC
## GET /search

### Description
Search across spools, filaments and vendors in a single request. Results are categorized by entity.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query
- **color_similarity_threshold** (number) - Optional - Similarity threshold for color matching (0-100, default: 20)
- **limit** (integer) - Optional - Maximum number of results per category (1-100, default: 20)
- **allow_archived** (boolean) - Optional - Whether to include archived spools (default: false)
- **spools_per_filament** (integer) - Optional - Number of spools to include per matching filament (0-10, default: 0)

### Response
#### Success Response (200)
- Successful Response

#### Error Response (422)
- Validation Error
```

--------------------------------

### GET /setting/{key}

Source: https://donkie.github.io/Spoolman

Retrieves a specific setting by its key. If the setting is not defined, the default value is returned.

```APIDOC
## GET /setting/{key}

### Description
Get a specific setting. If the setting has not been set, the default value will be returned. A websocket is served on the same path to listen for changes to the setting.

### Method
GET

### Endpoint
/setting/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - Key

### Response
#### Success Response (200)
- **value** (string) - The setting value
- **is_set** (boolean) - Whether the setting is explicitly set
- **type** (string) - The data type of the setting
```

--------------------------------

### Add Spool Successful Response

Source: https://donkie.github.io/Spoolman

Example JSON response returned upon successfully adding a spool.

```json
{
  "id": 0,
  "registered": "string",
  "first_used": "string",
  "last_used": "string",
  "filament": {
    "id": 0,
    "registered": "string",
    "name": "PolyTerra™ Charcoal Black",
    "vendor": {
      "id": 0,
      "registered": "string",
      "name": "Polymaker",
      "comment": "",
      "empty_spool_weight": 140,
      "external_id": "eSun",
      "extra": {
        "property1": "string",
        "property2": "string"
}
},
    "material": "PLA",
    "price": 20,
    "density": 1.24,
    "diameter": 1.75,
    "weight": 1000,
    "spool_weight": 140,
    "article_number": "PM70820",
    "comment": "",
    "settings_extruder_temp": 210,
    "settings_bed_temp": 60,
    "color_hex": "FF0000",
    "multi_color_hexes": "FF0000,00FF00,0000FF",
    "multi_color_direction": "coaxial",
    "external_id": "polymaker_pla_polysonicblack_1000_175",
    "extra": {
      "property1": "string",
      "property2": "string"
}
},
  "price": 20,
  "remaining_weight": 500.6,
  "initial_weight": 1246,
  "spool_weight": 246,
  "used_weight": 500.3,
  "remaining_length": 5612.4,
  "used_length": 50.7,
  "location": "Shelf A",
  "lot_nr": "52342",
  "comment": "",
  "archived": true,
  "extra": {
    "property1": "string",
    "property2": "string"
}

}
```

--------------------------------

### GET /export/vendors

Source: https://donkie.github.io/Spoolman

Export the list of vendors in various formats.

```APIDOC
## GET /export/vendors

### Description
Export the list of vendors in various formats.

### Method
GET

### Endpoint
/export/vendors

### Parameters
#### Query Parameters
- **fmt** (string) - Required - Export format (csv, json)

### Response
#### Success Response (200)
- Successful Response

#### Error Response (422)
- Validation Error
```

--------------------------------

### Vendor Response Schema

Source: https://donkie.github.io/Spoolman

Example JSON structure returned by the vendor API endpoint.

```json
[
  {
    "id": 0,
    "registered": "string",
    "name": "Polymaker",
    "comment": "",
    "empty_spool_weight": 140,
    "external_id": "eSun",
    "extra": {
      "property1": "string",
      "property2": "string"
    }
  }
]
```

--------------------------------

### GET /article-number

Source: https://donkie.github.io/Spoolman

Retrieve a list of all article numbers.

```APIDOC
## GET /article-number

### Description
Get a list of all article numbers.

### Method
GET

### Endpoint
/article-number

### Response
#### Success Response (200)
- **article_numbers** (array) - A list of all article numbers.
```

--------------------------------

### Add Filament Successful Response

Source: https://donkie.github.io/Spoolman

Example JSON response returned upon successfully adding a new filament.

```json
{
  "id": 0,
  "registered": "string",
  "name": "PolyTerra™ Charcoal Black",
  "vendor": {
    "id": 0,
    "registered": "string",
    "name": "Polymaker",
    "comment": "",
    "empty_spool_weight": 140,
    "external_id": "eSun",
    "extra": {
      "property1": "string",
      "property2": "string"
    }
  },
  "material": "PLA",
  "price": 20,
  "density": 1.24,
  "diameter": 1.75,
  "weight": 1000,
  "spool_weight": 140,
  "article_number": "PM70820",
  "comment": "",
  "settings_extruder_temp": 210,
  "settings_bed_temp": 60,
  "color_hex": "FF0000",
  "multi_color_hexes": "FF0000,00FF00,0000FF",
  "multi_color_direction": "coaxial",
  "external_id": "polymaker_pla_polysonicblack_1000_175",
  "extra": {
    "property1": "string",
    "property2": "string"
  }
}
```

--------------------------------

### Add Vendor Request Payload

Source: https://donkie.github.io/Spoolman

Example JSON payload for creating a new vendor entry.

```json
{
  "name": "Polymaker",
  "comment": "",
  "empty_spool_weight": 200,
  "external_id": "eSun",
  "extra": {
    "property1": "string",
    "property2": "string"
}

}
```

--------------------------------

### GET /external/filament

Source: https://donkie.github.io/Spoolman

Retrieves a list of all external filaments.

```APIDOC
## GET /external/filament

### Description
Get all external filaments.

### Method
GET

### Endpoint
/external/filament

### Response
#### Success Response (200)
- **filaments** (array) - A list of external filament objects.

#### Response Example
[
  {
    "id": "polymaker_pla_polysonicblack_1000_175",
    "manufacturer": "Polymaker",
    "name": "Polysonic™ Black",
    "material": "PLA",
    "density": 1.23,
    "weight": 1000,
    "spool_weight": 140,
    "spool_type": "plastic",
    "diameter": 1.75,
    "color_hex": "2c3232",
    "color_hexes": ["2c3232", "5f5f5f"],
    "extruder_temp": 210,
    "bed_temp": 50,
    "finish": "matte",
    "multi_color_direction": "coaxial",
    "pattern": "marble",
    "translucent": false,
    "glow": false
  }
]
```

--------------------------------

### Filament Response JSON Structure

Source: https://donkie.github.io/Spoolman

Example of the JSON object returned by the filament endpoint.

```json
[
  {
    "id": 0,
    "registered": "string",
    "name": "PolyTerra™ Charcoal Black",
    "vendor": {
      "id": 0,
      "registered": "string",
      "name": "Polymaker",
      "comment": "",
      "empty_spool_weight": 140,
      "external_id": "eSun",
      "extra": {
        "property1": "string",
        "property2": "string"
      }
    },
    "material": "PLA",
    "price": 20,
    "density": 1.24,
    "diameter": 1.75,
    "weight": 1000,
    "spool_weight": 140,
    "article_number": "PM70820",
    "comment": "",
    "settings_extruder_temp": 210,
    "settings_bed_temp": 60,
    "color_hex": "FF0000",
    "multi_color_hexes": "FF0000,00FF00,0000FF",
    "multi_color_direction": "coaxial",
    "external_id": "polymaker_pla_polysonicblack_1000_175",
    "extra": {
      "property1": "string",
      "property2": "string"
    }
  }
]
```

--------------------------------

### Get Setting Response Schema

Source: https://donkie.github.io/Spoolman

The JSON structure returned when retrieving a specific setting value.

```json
{
  "value": "string",
  "is_set": true,
  "type": "boolean"
}
```

--------------------------------

### GET /api/v1/health

Source: https://donkie.github.io/Spoolman

Returns the health status of the Spoolman service.

```APIDOC
## GET /api/v1/health

### Description
Return a health check.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
- **status** (string) - Health status

#### Response Example
{
  "status": "healthy"
}
```

--------------------------------

### Add Filament Request Payload

Source: https://donkie.github.io/Spoolman

Example JSON payload for creating a new filament entry.

```json
{
  "name": "PolyTerra™ Charcoal Black",
  "vendor_id": 0,
  "material": "PLA",
  "price": 20,
  "density": 1.24,
  "diameter": 1.75,
  "weight": 1000,
  "spool_weight": 140,
  "article_number": "PM70820",
  "comment": "",
  "settings_extruder_temp": 210,
  "settings_bed_temp": 60,
  "color_hex": "FF0000",
  "multi_color_hexes": "FF0000,00FF00,0000FF",
  "multi_color_direction": "coaxial",
  "external_id": "polymaker_pla_polysonicblack_1000_175",
  "extra": {
    "property1": "string",
    "property2": "string"
  }
}
```

--------------------------------

### Add Spool Request Payload

Source: https://donkie.github.io/Spoolman

Example JSON payload for creating a new spool entry.

```json
{
  "first_used": "2019-08-24T14:15:22Z",
  "last_used": "2019-08-24T14:15:22Z",
  "filament_id": 0,
  "price": 20,
  "initial_weight": 200,
  "spool_weight": 200,
  "remaining_weight": 800,
  "used_weight": 200,
  "location": "Shelf A",
  "lot_nr": "52342",
  "comment": "",
  "archived": false,
  "extra": {
    "property1": "string",
    "property2": "string"
}

}
```

--------------------------------

### GET /vendor

Source: https://donkie.github.io/Spoolman

Retrieves a list of vendors based on search criteria. A websocket is available on the same path for real-time updates.

```APIDOC
## GET /vendor

### Description
Get a list of vendors that matches the search query. A websocket is served on the same path to listen for updates to any vendor, or added or deleted vendors.

### Method
GET

### Endpoint
/vendor

### Parameters
#### Query Parameters
- **name** (string) - Optional - Partial case-insensitive search term for the vendor name.
- **external_id** (string) - Optional - Exact match for the vendor external ID.
- **sort** (string) - Optional - Sort the results by the given field (e.g., name:asc,id:desc).
- **limit** (integer) - Optional - Maximum number of items in the response.
- **offset** (integer) - Optional - Offset in the full result set if a limit is set.

### Response
#### Success Response (200)
- **id** (integer) - Vendor ID
- **registered** (string) - Registration timestamp
- **name** (string) - Vendor name
- **comment** (string) - Vendor comment
- **empty_spool_weight** (integer) - Weight of an empty spool
- **external_id** (string) - External ID
- **extra** (object) - Additional properties

#### Websocket Response (299)
- Websocket message for updates to any vendor, or added or deleted vendors.
```

--------------------------------

### GET /spool/{spool_id}

Source: https://donkie.github.io/Spoolman

Retrieves the details of a specific spool by its ID.

```APIDOC
## GET /spool/{spool_id}

### Description
Get a specific spool. A websocket is served on the same path to listen for changes to the spool.

### Method
GET

### Endpoint
/spool/{spool_id}

### Parameters
#### Path Parameters
- **spool_id** (integer) - Required - The ID of the spool to retrieve.

### Response
#### Success Response (200)
- **id** (integer) - Spool ID
- **registered** (string) - Registration timestamp
- **first_used** (string) - First use timestamp
- **last_used** (string) - Last use timestamp
- **filament** (object) - Filament details
- **price** (number) - Price
- **remaining_weight** (number) - Remaining weight
- **initial_weight** (number) - Initial weight
- **spool_weight** (number) - Spool weight
- **used_weight** (number) - Used weight
- **remaining_length** (number) - Remaining length
- **used_length** (number) - Used length
- **location** (string) - Location
- **lot_nr** (string) - Lot number
- **comment** (string) - Comment
- **archived** (boolean) - Archived status
- **extra** (object) - Extra fields
```

--------------------------------

### GET /export/filaments

Source: https://donkie.github.io/Spoolman

Export the list of filaments in various formats, including vendor data.

```APIDOC
## GET /export/filaments

### Description
Export the list of filaments in various formats. Vendor data is included.

### Method
GET

### Endpoint
/export/filaments

### Parameters
#### Query Parameters
- **fmt** (string) - Required - Export format (csv, json)

### Response
#### Success Response (200)
- Successful Response

#### Error Response (422)
- Validation Error
```

--------------------------------

### Get Spool Details Response

Source: https://donkie.github.io/Spoolman

JSON structure returned when retrieving a specific spool by ID.

```json
{
  "id": 0,
  "registered": "string",
  "first_used": "string",
  "last_used": "string",
  "filament": {
    "id": 0,
    "registered": "string",
    "name": "PolyTerra™ Charcoal Black",
    "vendor": {
      "id": 0,
      "registered": "string",
      "name": "Polymaker",
      "comment": "",
      "empty_spool_weight": 140,
      "external_id": "eSun",
      "extra": {
        "property1": "string",
        "property2": "string"
      }
    },
    "material": "PLA",
    "price": 20,
    "density": 1.24,
    "diameter": 1.75,
    "weight": 1000,
    "spool_weight": 140,
    "article_number": "PM70820",
    "comment": "",
    "settings_extruder_temp": 210,
    "settings_bed_temp": 60,
    "color_hex": "FF0000",
    "multi_color_hexes": "FF0000,00FF00,0000FF",
    "multi_color_direction": "coaxial",
    "external_id": "polymaker_pla_polysonicblack_1000_175",
    "extra": {
      "property1": "string",
      "property2": "string"
    }
  },
  "price": 20,
  "remaining_weight": 500.6,
  "initial_weight": 1246,
  "spool_weight": 246,
  "used_weight": 500.3,
  "remaining_length": 5612.4,
  "used_length": 50.7,
  "location": "Shelf A",
  "lot_nr": "52342",
  "comment": "",
  "archived": true,
  "extra": {
    "property1": "string",
    "property2": "string"
  }
}
```

--------------------------------

### GET /spool

Source: https://donkie.github.io/Spoolman

Retrieves a list of spools matching the provided search criteria. A websocket is available on this path for real-time updates.

```APIDOC
## GET /spool

### Description
Get a list of spools that matches the search query. A websocket is served on the same path to listen for updates to any spool, or added or deleted spools.

### Method
GET

### Endpoint
/spool

### Parameters
#### Query Parameters
- **filament.name** (string) - Optional - Partial case-insensitive search term for the filament name.
- **filament.id** (string) - Optional - Match an exact filament ID.
- **filament.material** (string) - Optional - Partial case-insensitive search term for the filament material.
- **filament.multi_color_direction** (string) - Optional - Match spools by their filament's multi-color direction.
- **filament.vendor.name** (string) - Optional - Partial case-insensitive search term for the filament vendor name.
- **filament.vendor.id** (string) - Optional - Match an exact vendor ID.
- **location** (string) - Optional - Partial case-insensitive search term for the spool location.
- **lot_nr** (string) - Optional - Partial case-insensitive search term for the spool lot number.
- **allow_archived** (boolean) - Optional - Whether to include archived spools in the search results. Default: false.
- **sort** (string) - Optional - Sort the results by the given field.
- **limit** (integer) - Optional - Maximum number of items in the response.
- **offset** (integer) - Optional - Offset in the full result set. Default: 0.

### Response
#### Success Response (200)
- Successful Response

#### Other Responses
- **299** - Websocket message
- **422** - Validation Error
```

--------------------------------

### API Response JSON Structure

Source: https://donkie.github.io/Spoolman

Example of a successful 200 response containing lists of spools, filaments, and vendors.

```json
{
  "spools": [
    {
      "spool": {
        "id": 0,
        "registered": "string",
        "first_used": "string",
        "last_used": "string",
        "filament": {
          "id": 0,
          "registered": "string",
          "name": "PolyTerra™ Charcoal Black",
          "vendor": {
            "id": 0,
            "registered": "string",
            "name": "Polymaker",
            "comment": "",
            "empty_spool_weight": 140,
            "external_id": "eSun",
            "extra": {
              "property1": "string",
              "property2": "string"
            }
          },
          "material": "PLA",
          "price": 20,
          "density": 1.24,
          "diameter": 1.75,
          "weight": 1000,
          "spool_weight": 140,
          "article_number": "PM70820",
          "comment": "",
          "settings_extruder_temp": 210,
          "settings_bed_temp": 60,
          "color_hex": "FF0000",
          "multi_color_hexes": "FF0000,00FF00,0000FF",
          "multi_color_direction": "coaxial",
          "external_id": "polymaker_pla_polysonicblack_1000_175",
          "extra": {
            "property1": "string",
            "property2": "string"
          }
        },
        "price": 20,
        "remaining_weight": 500.6,
        "initial_weight": 1246,
        "spool_weight": 246,
        "used_weight": 500.3,
        "remaining_length": 5612.4,
        "used_length": 50.7,
        "location": "Shelf A",
        "lot_nr": "52342",
        "comment": "",
        "archived": true,
        "extra": {
          "property1": "string",
          "property2": "string"
        }
      },
      "match_field": "comment"
    }
  ],
  "filaments": [
    {
      "filament": {
        "id": 0,
        "registered": "string",
        "name": "PolyTerra™ Charcoal Black",
        "vendor": {
          "id": 0,
          "registered": "string",
          "name": "Polymaker",
          "comment": "",
          "empty_spool_weight": 140,
          "external_id": "eSun",
          "extra": {
            "property1": "string",
            "property2": "string"
          }
        },
        "material": "PLA",
        "price": 20,
        "density": 1.24,
        "diameter": 1.75,
        "weight": 1000,
        "spool_weight": 140,
        "article_number": "PM70820",
        "comment": "",
        "settings_extruder_temp": 210,
        "settings_bed_temp": 60,
        "color_hex": "FF0000",
        "multi_color_hexes": "FF0000,00FF00,0000FF",
        "multi_color_direction": "coaxial",
        "external_id": "polymaker_pla_polysonicblack_1000_175",
        "extra": {
          "property1": "string",
          "property2": "string"
        }
      },
      "match_field": "color",
      "spools": [
        {
          "id": 0,
          "remaining_weight": 500.6,
          "location": "Shelf A",
          "archived": true
        }
      ],
      "spool_count": 3
    }
  ],
  "vendors": [
    {
      "vendor": {
        "id": 0,
        "registered": "string",
        "name": "Polymaker",
        "comment": "",
        "empty_spool_weight": 140,
        "external_id": "eSun",
        "extra": {
          "property1": "string",
          "property2": "string"
        }
      },
      "match_field": "name"
    }
  ],
  "is_color_query": false
}
```

--------------------------------

### GET /vendor/{vendor_id}

Source: https://donkie.github.io/Spoolman

Retrieves details for a specific vendor. A websocket is available on the same path to listen for updates.

```APIDOC
## GET /vendor/{vendor_id}

### Description
Get a specific vendor. A websocket is served on the same path to listen for changes to the vendor.

### Method
GET

### Endpoint
/vendor/{vendor_id}

### Parameters
#### Path Parameters
- **vendor_id** (integer) - Required - Vendor Id

### Response
#### Success Response (200)
- **id** (integer) - Vendor ID
- **registered** (string) - Registration timestamp
- **name** (string) - Vendor name
- **comment** (string) - Free text comment
- **empty_spool_weight** (number) - Weight of empty spool in grams
- **external_id** (string) - External database ID
- **extra** (object) - Extra fields

#### Response Example
{
  "id": 0,
  "registered": "string",
  "name": "Polymaker",
  "comment": "",
  "empty_spool_weight": 140,
  "external_id": "eSun",
  "extra": {
    "property1": "string",
    "property2": "string"
  }
}
```

--------------------------------

### GET /export/spools

Source: https://donkie.github.io/Spoolman

Export the list of spools in various formats, including filament and vendor data.

```APIDOC
## GET /export/spools

### Description
Export the list of spools in various formats. Filament and vendor data is included.

### Method
GET

### Endpoint
/export/spools

### Parameters
#### Query Parameters
- **fmt** (string) - Required - Export format (csv, json)
- **allow_archived** (boolean) - Optional - Whether to include archived spools in the export (default: false)

### Response
#### Success Response (200)
- Successful Response

#### Error Response (422)
- Validation Error
```

--------------------------------

### GET /field/{entity_type}

Source: https://donkie.github.io/Spoolman

Retrieves all extra fields defined for a specific entity type.

```APIDOC
## GET /field/{entity_type}

### Description
Get all extra fields for a specific entity type.

### Method
GET

### Endpoint
/field/{entity_type}

### Parameters
#### Path Parameters
- **entity_type** (string) - Required - Entity type this field is for (Enum: "vendor", "filament", "spool")

### Response
#### Success Response (200)
- **fields** (array) - A list of extra field definitions.

#### Response Example
[
  {
    "name": "string",
    "order": 0,
    "unit": "string",
    "field_type": "text",
    "default_value": "string",
    "choices": ["string"],
    "multi_choice": true,
    "key": "string",
    "entity_type": "vendor"
  }
]
```

--------------------------------

### GET /external/filament/search

Source: https://donkie.github.io/Spoolman

Search the external filament catalog using a query string and limit the number of results.

```APIDOC
## GET /external/filament/search

### Description
Search the external filament catalog. Filters server-side so clients don't have to download the entire catalog just to search it.

### Method
GET

### Endpoint
/external/filament/search

### Parameters
#### Query Parameters
- **query** (string) - Required - Search query, matched word-by-word against manufacturer, name and material.
- **limit** (integer) - Optional - Maximum number of results to return (1-100, default: 20).

### Response
#### Success Response (200)
- **id** (string) - Filament ID
- **manufacturer** (string) - Manufacturer name
- **name** (string) - Filament name
- **material** (string) - Material type
- **density** (number) - Material density
- **weight** (integer) - Total weight
- **spool_weight** (integer) - Spool weight
- **spool_type** (string) - Type of spool
- **diameter** (number) - Filament diameter
- **color_hex** (string) - Primary color hex code
- **color_hexes** (array) - List of color hex codes
- **extruder_temp** (integer) - Recommended extruder temperature
- **bed_temp** (integer) - Recommended bed temperature
- **finish** (string) - Filament finish
- **multi_color_direction** (string) - Multi-color direction
- **pattern** (string) - Filament pattern
- **translucent** (boolean) - Translucency status
- **glow** (boolean) - Glow-in-the-dark status
```

--------------------------------

### Update Spool Request Payload

Source: https://donkie.github.io/Spoolman

Example JSON payload for updating a spool's attributes.

```json
{
  "first_used": "2019-08-24T14:15:22Z",
  "last_used": "2019-08-24T14:15:22Z",
  "filament_id": 0,
  "price": 20,
  "initial_weight": 200,
  "spool_weight": 200,
  "remaining_weight": 800,
  "used_weight": 200,
  "location": "Shelf A",
  "lot_nr": "52342",
  "comment": "",
  "archived": false,
  "extra": {
    "property1": "string",
    "property2": "string"
  }
}
```

--------------------------------

### Retrieve Spool Data JSON Response

Source: https://donkie.github.io/Spoolman

Example of a successful JSON response containing spool details, including filament properties and weight metrics.

```json
[
  {
    "id": 0,
    "registered": "string",
    "first_used": "string",
    "last_used": "string",
    "filament": {
      "id": 0,
      "registered": "string",
      "name": "PolyTerra™ Charcoal Black",
      "vendor": {
        "id": 0,
        "registered": "string",
        "name": "Polymaker",
        "comment": "",
        "empty_spool_weight": 140,
        "external_id": "eSun",
        "extra": {
          "property1": "string",
          "property2": "string"
        }
      },
      "material": "PLA",
      "price": 20,
      "density": 1.24,
      "diameter": 1.75,
      "weight": 1000,
      "spool_weight": 140,
      "article_number": "PM70820",
      "comment": "",
      "settings_extruder_temp": 210,
      "settings_bed_temp": 60,
      "color_hex": "FF0000",
      "multi_color_hexes": "FF0000,00FF00,0000FF",
      "multi_color_direction": "coaxial",
      "external_id": "polymaker_pla_polysonicblack_1000_175",
      "extra": {
        "property1": "string",
        "property2": "string"
      }
    },
    "price": 20,
    "remaining_weight": 500.6,
    "initial_weight": 1246,
    "spool_weight": 246,
    "used_weight": 500.3,
    "remaining_length": 5612.4,
    "used_length": 50.7,
    "location": "Shelf A",
    "lot_nr": "52342",
    "comment": "",
    "archived": true,
    "extra": {
      "property1": "string",
      "property2": "string"
    }
  }
]
```

--------------------------------

### Spool Group Response JSON

Source: https://donkie.github.io/Spoolman

Example JSON response structure for the spool group aggregation endpoint.

```json
[
  {
    "group_by": "filament",
    "key": "12",
    "spool_count": 6,
    "in_use_count": 2,
    "total_remaining_weight": 3120,
    "last_used": "string",
    "filament": {
      "id": 0,
      "registered": "string",
      "name": "PolyTerra™ Charcoal Black",
      "vendor": {
        "id": 0,
        "registered": "string",
        "name": "Polymaker",
        "comment": "",
        "empty_spool_weight": 140,
        "external_id": "eSun",
        "extra": {
          "property1": "string",
          "property2": "string"
        }
      },
      "material": "PLA",
      "price": 20,
      "density": 1.24,
      "diameter": 1.75,
      "weight": 1000,
      "spool_weight": 140,
      "article_number": "PM70820",
      "comment": "",
      "settings_extruder_temp": 210,
      "settings_bed_temp": 60,
      "color_hex": "FF0000",
      "multi_color_hexes": "FF0000,00FF00,0000FF",
      "multi_color_direction": "coaxial",
      "external_id": "polymaker_pla_polysonicblack_1000_175",
      "extra": {
        "property1": "string",
        "property2": "string"
      }
    },
    "vendor": {
      "id": 0,
      "registered": "string",
      "name": "Polymaker",
      "comment": "",
      "empty_spool_weight": 140,
      "external_id": "eSun",
      "extra": {
        "property1": "string",
        "property2": "string"
      }
    }
  }
]
```

--------------------------------

### GET /filament

Source: https://donkie.github.io/Spoolman

Retrieves a list of filaments matching the provided search criteria. A websocket is also available on this path for real-time updates.

```APIDOC
## GET /filament

### Description
Get a list of filaments that matches the search query. A websocket is served on the same path to listen for updates to any filament, or added or deleted filaments.

### Method
GET

### Endpoint
/filament

### Parameters
#### Query Parameters
- **vendor_name** (string) - Optional - Deprecated. See vendor.name.
- **vendor_id** (string) - Optional - Deprecated. See vendor.id.
- **vendor.name** (string) - Optional - Partial case-insensitive search term for the filament vendor name.
- **vendor.id** (string) - Optional - Match an exact vendor ID. Separate multiple IDs with a comma.
- **name** (string) - Optional - Partial case-insensitive search term for the filament name.
- **material** (string) - Optional - Partial case-insensitive search term for the filament material.
- **article_number** (string) - Optional - Partial case-insensitive search term for the filament article number.
- **color_hex** (string) - Optional - Match filament by similar color.
- **color_similarity_threshold** (number) - Optional - The similarity threshold for color matching (0.0-100.0).
- **external_id** (string) - Optional - Find filaments imported by the given external ID.
- **sort** (string) - Optional - Sort the results by the given field (e.g., vendor.name:asc).
- **limit** (integer) - Optional - Maximum number of items in the response.
- **offset** (integer) - Optional - Offset in the full result set.

### Response
#### Success Response (200)
- **id** (integer) - Filament ID
- **registered** (string) - Registration timestamp
- **name** (string) - Filament name
- **vendor** (object) - Vendor details
- **material** (string) - Filament material
- **price** (number) - Price
- **density** (number) - Density
- **diameter** (number) - Diameter
- **weight** (number) - Weight
- **spool_weight** (number) - Spool weight
- **article_number** (string) - Article number
- **comment** (string) - Comment
- **settings_extruder_temp** (integer) - Extruder temperature setting
- **settings_bed_temp** (integer) - Bed temperature setting
- **color_hex** (string) - Color hex code
- **multi_color_hexes** (string) - Multi-color hex codes
- **multi_color_direction** (string) - Multi-color direction
- **external_id** (string) - External ID
- **extra** (object) - Extra properties
```

--------------------------------

### Get Extra Fields Response Format

Source: https://donkie.github.io/Spoolman

The structure of the JSON response containing a list of extra fields for a specific entity type.

```json
[
  {
    "name": "string",
    "order": 0,
    "unit": "string",
    "field_type": "text",
    "default_value": "string",
    "choices": [
      "string"
],
    "multi_choice": true,
    "key": "string",
    "entity_type": "vendor"
}

]
```

--------------------------------

### GET /filament/{filament_id}

Source: https://donkie.github.io/Spoolman

Retrieves details for a specific filament by its ID. A websocket is also available on this path to receive updates.

```APIDOC
## GET /filament/{filament_id}

### Description
Get a specific filament. A websocket is served on the same path to listen for changes to the filament.

### Method
GET

### Endpoint
/filament/{filament_id}

### Parameters
#### Path Parameters
- **filament_id** (integer) - Required - Filament Id

### Response
#### Success Response (200)
- **id** (integer)
- **registered** (string)
- **name** (string)
- **vendor** (object)
- **material** (string)
- **price** (number)
- **density** (number)
- **diameter** (number)
- **weight** (number)
- **spool_weight** (number)
- **article_number** (string)
- **comment** (string)
- **settings_extruder_temp** (integer)
- **settings_bed_temp** (integer)
- **color_hex** (string)
- **multi_color_hexes** (string)
- **multi_color_direction** (string)
- **external_id** (string)
- **extra** (object)

#### Response Example
{
  "id": 0,
  "registered": "string",
  "name": "PolyTerra™ Charcoal Black",
  "vendor": {
    "id": 0,
    "registered": "string",
    "name": "Polymaker",
    "comment": "",
    "empty_spool_weight": 140,
    "external_id": "eSun",
    "extra": {
      "property1": "string",
      "property2": "string"
    }
  },
  "material": "PLA",
  "price": 20,
  "density": 1.24,
  "diameter": 1.75,
  "weight": 1000,
  "spool_weight": 140,
  "article_number": "PM70820",
  "comment": "",
  "settings_extruder_temp": 210,
  "settings_bed_temp": 60,
  "color_hex": "FF0000",
  "multi_color_hexes": "FF0000,00FF00,0000FF",
  "multi_color_direction": "coaxial",
  "external_id": "polymaker_pla_polysonicblack_1000_175",
  "extra": {
    "property1": "string",
    "property2": "string"
  }
}
```

--------------------------------

### Get Extra Field Values Response Format

Source: https://donkie.github.io/Spoolman

The structure of the JSON response containing a list of distinct values for a specific extra field.

```json
[
  "string"

]
```
Tokens:
Raw