---
title: "Create a new Print."
method: POST
path: "/api/Prints"
tags: ["Prints"]
---

# Create a new Print.

`POST /api/Prints`

## Request

- Base URL: `https://api.3dprintlog.com`
- URL: `https://api.3dprintlog.com/api/Prints`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://3dprintlog.auth0.com/authorize`, token URL `https://3dprintlog.auth0.com/oauth/token`)
  - API key in header `X-Api-Key`
  - API key in query parameter `api_key`

`title` is required, and `printerId` is the id of one of the caller's printers. Durations are
in seconds and filament amounts in milligrams. `status` is an integer (`1` Pending,
`2` Printing, `3` Success, `4` Cancelled, `5` Failed, `6` PartialSuccess), and `viewStatus`
is `1` Public, `2` Unlisted or `3` Private.
            
Connectors should send `externalSource` (e.g. `moonraker`) and `externalId` (their job id)
together. Re-sending a pair you already used returns that print with `200` instead of
creating a duplicate, so retries and backfills are safe. On such a replay only the fields a
connector owns are applied (`status`, the durations, the filament totals and the usage
rows), and only when sent; the title, notes and every other field keep any edits the user
made. A replay with `status` Pending or Printing, or with no `status`, onto a finished print
changes nothing and returns the print as it is, so a start retried after the finish cannot
undo it. `mcp` is reserved.
            
`fileHash` is optional: 40 hex digits (20 bytes) identifying the G-code file, either its
SHA-1 or a connector's own identity for it. A replay never changes it.

## Request body

- PrintLogApiModelsDTOsPrintAddPrintDTO
  - `printerId` integer
  - `estimatedPrintTimeInSeconds` integer, nullable
  - `estimatedFilamentUsageMg` integer, nullable
  - `printTimeInSeconds` integer, nullable
  - `filamentUsageMg` integer, nullable: Filament usage in milligrams
  - `filamentType` string, nullable
  - `filamentUsage` PrintLogApiModelsDTOsPrintPrintFilamentSummaryDto[], nullable
    - `id` string, uuid
    - `filament` PrintLogApiModelsDTOsFilamentFilamentSummaryDto
      - `id` string, uuid
      - `spoolNumber` integer, nullable: The user's own number for this spool (1, 2, 3…), which Spoolman clients use as its id. Read-only: assigned on create, never reused, and ignored on PUT.
      - `displayName` string, nullable: Common name for the roll of filament.
      - `brand` string, nullable
      - `materialType` string, nullable: The material Type, ie PLA, PETG, ABS.
      - `materialCategory` PrintLogApiModelsDTOsMaterialCategoryMaterialCategoryDto: The category of materials, such as filament, resin, powder, etc.
        - `nickname` string, nullable: The nickname of the material category
        - `name` string, nullable: The long form name of the category
        - `description` string, nullable: A description of that category
        - `hasDiameter` boolean: Whether this material has a diameter
        - `showNozzleTemperature` boolean
        - `showBedTemperature` boolean
        - `showMeltingTemperature` boolean
        - `showRecommendedInitialLayerTimeInSeconds` boolean
        - `showRecommendedLayerTimeInSeconds` boolean
        - `showMaterialRefreshRatio` boolean: The percentage of new powder when mixing with old powder
        - `showInertGas` boolean
      - `materialDensityGramPerCubicCm` number, double: The Density of the Material
      - `colorName` string, nullable
      - `colorHex` string, nullable
      - `recommendedTemp` number, double, nullable: The user's recommended temperature
      - `isActive` boolean
      - `notes` string, nullable
      - `createdDate` string, date-time
      - `filamentRemaining` integer, nullable
      - `filamentLengthRemainingInM` number, double, nullable: Converted from FilamentRemaining rather than accumulated separately, so the list and the detail page cannot disagree. See FilamentDetailDto for why the per-usage volume and length columns are not summed. Get-only: computed on read.
      - `filamentVolumeRemainingInMl` number, double, nullable
      - `purchasePriceValue` string, nullable: Any notes about the purchase price
      - `initialNominalWeightMg` integer, nullable
      - `diameterMm` number, double, nullable
      - `loadedInPrinter` PrintLogApiModelsDTOsPrinterPrinterSummaryWithoutCategory
        - `id` integer
        - `name` string, nullable
        - `make` string, nullable
        - `model` string, nullable
        - `isActive` boolean
      - `storageLocation` string, nullable
      - `isFavorite` boolean
      - `colorPattern` 1 | 2 | 3 | 4: Sent as an integer: `1` = Solid, `2` = Multi, `3` = Gradient, `4` = Rainbow.
      - `finishType` 1 | 2 | 3: Sent as an integer: `1` = Standard, `2` = Silk, `3` = Matte.
      - `colors` string[], nullable
      - `effects` PrintLogApiEnumsFilamentEffect[], nullable
      - `defaultImageThumbnailUrl` string, nullable: Signed thumbnail URL for the default image. Populated ONLY by FilamentService's explicit hydration for the owner's filament list. Null everywhere else — including inside print responses, which are anonymous. Never populate this via AutoMapper.
    - `slot` integer, nullable: The printer slot (tool) the material was fed from, if known.
    - `estimatedAmountMg` integer, nullable
    - `amountMg` integer, nullable
    - `estimatedLengthInM` number, double, nullable: The estimated length of filament used in meters.
    - `lengthInM` number, double, nullable: The actual length of filament used in meters.
    - `estimatedVolumeMl` number, double, nullable: The estimated volume of filament used in milliliters.
    - `volumeMl` number, double, nullable: The actual volume of filament used in milliliters
    - `isEstimatedLengthSource` boolean: Determines if the user entered the length as the "source of truth", or weight. True means the user entered the filament usage as a length, while false means the user entered usage as Mg.
    - `isActualLengthSource` boolean: Determines if the user entered the length as the "source of truth", or weight. True means the user entered the filament usage as a length, while false means the user entered usage as Mg.
    - `estimatedSource` 1 | 2 | 3: Which field is the user-entered "source" Sent as an integer: `1` = Weight, `2` = Length, `3` = Volume.
    - `source` 1 | 2 | 3: Which field is the user-entered "source" Sent as an integer: `1` = Weight, `2` = Length, `3` = Volume.
    - `notes` string, nullable
  - `notes` string, nullable
  - `url` string, nullable
  - `title` string, required
  - `fileName` string, nullable
  - `startDate` string, date-time, nullable
  - `status` 1 | 2 | 3 | 4 | 5 | 6: Sent as an integer: `1` = Pending, `2` = Printing, `3` = Success, `4` = Cancelled, `5` = Failed, `6` = PartialSuccess.
  - `viewStatus` 1 | 2 | 3: Sent as an integer: `1` = Public, `2` = Unlisted, `3` = Private.
  - `allowComments` boolean
  - `projectId` string, uuid, nullable: Assign to an existing project. Takes precedence over NewProjectName.
  - `newProjectName` string, nullable: Create a new project inline and assign this print to it. Ignored if ProjectId is set.
  - `curaSettingId` string, uuid, nullable: The `CuraSetting` this print was prefilled from, when it came through the slicer plugin. Only provenance: the slicer name and version are copied onto the print. An id that is missing (purged) or owned by someone else is ignored, never rejected.
  - `externalSource` string, nullable: The system a connector logged this print from, e.g. `moonraker`, `octoprint`. Send together with PrintLogApi.Models.DTOs.Print.AddPrintDTO.ExternalId: a pair the caller already used returns the existing print with 200 instead of creating a duplicate.
  - `externalId` string, nullable: The job's identity in PrintLogApi.Models.DTOs.Print.AddPrintDTO.ExternalSource, unique per user and source. Matched case-insensitively: `ABc1` replays a print created as `abC1`.
  - `connectionInstanceId` string, nullable: The `instanceId` of the connection (`PUT /api/Connections/{instanceId}`) logging this print, so it shows "Logged automatically by" that connection. An id that is not one of yours is ignored, never rejected.
  - `fileHash` string, nullable: The file's identity, 40 hex digits (20 bytes): the SHA-1 of the G-code, or a connector's own identity for the file that is the same for every job of it and changes when it is re-sliced (printlog-bridge#40). Your prints with the same hash are prints of the same file.

## Response `200`

Returned when `externalSource`/`externalId` matched one of your prints, containing that print.

- PrintLogApiModelsDTOsPrintPrintDetailDTO
  - `id` integer
  - `title` string, nullable
  - `startDate` string, date-time, nullable
  - `printerId` integer
  - `printer` PrintLogApiModelsDTOsPrinterPrinterSummary
    - `id` integer
    - `name` string, nullable
    - `make` string, nullable
    - `model` string, nullable
    - `isActive` boolean
    - `wattageW` number, double, nullable
    - `printTimeInSeconds` integer, nullable
    - `category` PrintLogApiModelsDTOsPrinterCategoryPrinterCategoryDto: The class/category/type of 3D printing technology, such as FDM, SLA, etc
      - `nickname` string, nullable: The nickname of the category
      - `name` string, nullable: The long form name of the category
      - `description` string, nullable: A description of that category
      - `materialCategory` PrintLogApiModelsDTOsMaterialCategoryMaterialCategoryDto: The category of materials, such as filament, resin, powder, etc.
        - `nickname` string, nullable: The nickname of the material category
        - `name` string, nullable: The long form name of the category
        - `description` string, nullable: A description of that category
        - `hasDiameter` boolean: Whether this material has a diameter
        - `showNozzleTemperature` boolean
        - `showBedTemperature` boolean
        - `showMeltingTemperature` boolean
        - `showRecommendedInitialLayerTimeInSeconds` boolean
        - `showRecommendedLayerTimeInSeconds` boolean
        - `showMaterialRefreshRatio` boolean: The percentage of new powder when mixing with old powder
        - `showInertGas` boolean
      - `showNozzleDiameter` boolean
      - `showFilamentDiameter` boolean
      - `showBeamDiameter` boolean
      - `showBedSize` boolean
      - `showScreenResolution` boolean
      - `showHasHeatedBed` boolean
      - `showHasHeatedChamber` boolean
  - `estimatedPrintTimeInSeconds` integer, nullable
  - `estimatedFilamentUsageMg` integer, nullable
  - `printTimeInSeconds` integer, nullable
  - `filamentUsageMg` integer, nullable: Filament usage in milligrams
  - `filamentType` string, nullable
  - `filamentUsage` PrintLogApiModelsDTOsPrintPrintFilamentSummaryDto[], nullable
    - `id` string, uuid
    - `filament` PrintLogApiModelsDTOsFilamentFilamentSummaryDto
      - `id` string, uuid
      - `spoolNumber` integer, nullable: The user's own number for this spool (1, 2, 3…), which Spoolman clients use as its id. Read-only: assigned on create, never reused, and ignored on PUT.
      - `displayName` string, nullable: Common name for the roll of filament.
      - `brand` string, nullable
      - `materialType` string, nullable: The material Type, ie PLA, PETG, ABS.
      - `materialCategory` PrintLogApiModelsDTOsMaterialCategoryMaterialCategoryDto: The category of materials, such as filament, resin, powder, etc.
        - `nickname` string, nullable: The nickname of the material category
        - `name` string, nullable: The long form name of the category
        - `description` string, nullable: A description of that category
        - `hasDiameter` boolean: Whether this material has a diameter
        - `showNozzleTemperature` boolean
        - `showBedTemperature` boolean
        - `showMeltingTemperature` boolean
        - `showRecommendedInitialLayerTimeInSeconds` boolean
        - `showRecommendedLayerTimeInSeconds` boolean
        - `showMaterialRefreshRatio` boolean: The percentage of new powder when mixing with old powder
        - `showInertGas` boolean
      - `materialDensityGramPerCubicCm` number, double: The Density of the Material
      - `colorName` string, nullable
      - `colorHex` string, nullable
      - `recommendedTemp` number, double, nullable: The user's recommended temperature
      - `isActive` boolean
      - `notes` string, nullable
      - `createdDate` string, date-time
      - `filamentRemaining` integer, nullable
      - `filamentLengthRemainingInM` number, double, nullable: Converted from FilamentRemaining rather than accumulated separately, so the list and the detail page cannot disagree. See FilamentDetailDto for why the per-usage volume and length columns are not summed. Get-only: computed on read.
      - `filamentVolumeRemainingInMl` number, double, nullable
      - `purchasePriceValue` string, nullable: Any notes about the purchase price
      - `initialNominalWeightMg` integer, nullable
      - `diameterMm` number, double, nullable
      - `loadedInPrinter` PrintLogApiModelsDTOsPrinterPrinterSummaryWithoutCategory
        - `id` integer
        - `name` string, nullable
        - `make` string, nullable
        - `model` string, nullable
        - `isActive` boolean
      - `storageLocation` string, nullable
      - `isFavorite` boolean
      - `colorPattern` 1 | 2 | 3 | 4: Sent as an integer: `1` = Solid, `2` = Multi, `3` = Gradient, `4` = Rainbow.
      - `finishType` 1 | 2 | 3: Sent as an integer: `1` = Standard, `2` = Silk, `3` = Matte.
      - `colors` string[], nullable
      - `effects` PrintLogApiEnumsFilamentEffect[], nullable
      - `defaultImageThumbnailUrl` string, nullable: Signed thumbnail URL for the default image. Populated ONLY by FilamentService's explicit hydration for the owner's filament list. Null everywhere else — including inside print responses, which are anonymous. Never populate this via AutoMapper.
    - `slot` integer, nullable: The printer slot (tool) the material was fed from, if known.
    - `estimatedAmountMg` integer, nullable
    - `amountMg` integer, nullable
    - `estimatedLengthInM` number, double, nullable: The estimated length of filament used in meters.
    - `lengthInM` number, double, nullable: The actual length of filament used in meters.
    - `estimatedVolumeMl` number, double, nullable: The estimated volume of filament used in milliliters.
    - `volumeMl` number, double, nullable: The actual volume of filament used in milliliters
    - `isEstimatedLengthSource` boolean: Determines if the user entered the length as the "source of truth", or weight. True means the user entered the filament usage as a length, while false means the user entered usage as Mg.
    - `isActualLengthSource` boolean: Determines if the user entered the length as the "source of truth", or weight. True means the user entered the filament usage as a length, while false means the user entered usage as Mg.
    - `estimatedSource` 1 | 2 | 3: Which field is the user-entered "source" Sent as an integer: `1` = Weight, `2` = Length, `3` = Volume.
    - `source` 1 | 2 | 3: Which field is the user-entered "source" Sent as an integer: `1` = Weight, `2` = Length, `3` = Volume.
    - `notes` string, nullable
  - `notes` string, nullable
  - `url` string, nullable
  - `fileName` string, nullable
  - `createdByUserId` integer
  - `allowComments` boolean
  - `allowFileDownloads` boolean
  - `status` 1 | 2 | 3 | 4 | 5 | 6: Sent as an integer: `1` = Pending, `2` = Printing, `3` = Success, `4` = Cancelled, `5` = Failed, `6` = PartialSuccess.
  - `viewStatus` 1 | 2 | 3: Sent as an integer: `1` = Public, `2` = Unlisted, `3` = Private.
  - `projectId` string, uuid, nullable
  - `images` PrintLogApiModelsDTOsPrintPrintImageDto[], nullable
    - `id` integer
    - `isDefault` boolean
    - `displayOrder` integer
  - `comments` PrintLogApiModelsDTOsCommentsCommentDetailDto[], nullable
    - `id` integer
    - `body` string, nullable
    - `createdDate` string, date-time
    - `createdById` integer
    - `createdBy` PrintLogApiModelsDTOsUserUserSummaryDto
      - `id` integer
      - `profilePicture` string, nullable: URL pointing to the user's profile picture.
      - `coverPicture` string, nullable: URL pointing to the user's cover picture.
      - `displayName` string, nullable
    - `updatedDate` string, date-time
    - `updatedById` integer
    - `updatedBy` PrintLogApiModelsDTOsUserUserSummaryDto
      - `id` integer
      - `profilePicture` string, nullable: URL pointing to the user's profile picture.
      - `coverPicture` string, nullable: URL pointing to the user's cover picture.
      - `displayName` string, nullable
  - `externalSource` string, nullable: The connector that logged this print, if any. Read-only; shown to the creator only.
  - `externalId` string, nullable: The job's id in PrintLogApi.Models.DTOs.Print.PrintDetailDTO.ExternalSource. Read-only; shown to the creator only.
  - `connectionDisplayName` string, nullable: The display name of the connection that logged this print, for "Logged automatically by …". Null when no connection logged it or it has been deleted. Shown to the creator only.

## Other responses

- `201`: Returned if the create was successful, containing the new Print Detail information.
- `400`: Returned if the new Print is not valid, including a malformed `fileHash`. Inspect Problem Details object for message as to what failed validation.
- `401`: Unauthorized
- `403`: Forbidden

---

[API](https://skmtc.dev/3dprintlog/apis/3d-print-log-api.md) · [All operations](https://skmtc.dev/3dprintlog/apis/3d-print-log-api/llms.txt) · [OpenAPI document](https://skmtc.dev/3dprintlog/apis/3d-print-log-api/revisions/dfc3a4df4e38?raw)