# Designs

Approved print files your SKUs use, with short-lived download links.

## Endpoints

-   [GET `/v1/print-farm/designs`](https://public-api.dapi.digital/docs/reference/print-farm-designs.md#listPrintFarmDesigns)
-   [GET `/v1/print-farm/designs/{id}`](https://public-api.dapi.digital/docs/reference/print-farm-designs.md#getPrintFarmDesign)

## The design object

### Attributes

-   `id` (string): Opaque public identifier for this design (`dsg_` prefix + 33 base62 chars). Use this value verbatim when referencing the design in other endpoints.
-   `name` (string): Display name of the design.
-   `description` (object, optional): Free-text description of the design.
-   `color_number` (object, optional): Number of distinct colours the design uses.
-   `extra_parts` (object, optional): Free-text description of any non-printed parts needed.
-   `extra_parts_config` (object, optional): Structured configuration of the extra parts (e.g. quantities, images). Returned verbatim from storage.
-   `required_filament` (boolean): Whether the design requires a specific filament (see `materials_config` for the allowed set).
-   `ams_required` (boolean): Whether the design requires an Automatic Material System (AMS).
-   `assembly` (boolean): Whether the design requires post-print assembly.
-   `farm_instructions` (object, optional): Print-farm-facing instructions for producing the design.
-   `materials_config` (object, optional): Material configuration for the design. Shape: `{ mode, allowed_materials, saved_combinations? }`. Returned verbatim from storage.
-   `hours_multiplier` (object, optional): Multiplier applied to baseline print time when estimating production hours, as a numeric string.
-   `grams_multiplier` (object, optional): Multiplier applied to baseline filament usage when estimating grams, as a numeric string.
-   `post_processing_multiplier` (object, optional): Multiplier applied to baseline post-processing time, as a numeric string.
-   `design_files` (array of PrintFarmDesignFileDto): All model files for this design (STL/3MF/etc.), each with a short-lived presigned download URL. Sorted by upload date (newest first).
    -   `id` (string): Opaque public identifier for the file (`dfl_` prefix + 33 base62 chars). No endpoint currently consumes this id - it is provided for client-side tracking.
    -   `file_name` (string): Original file name.
    -   `file_type` (string): MIME type of the file.
    -   `size` (object, optional): File size in bytes, if known.
    -   `download_url` (string): Presigned GET URL for downloading the file.
    -   `url_expires_at` (string): ISO 8601 timestamp at which `download_url` expires. Re-fetch the parent resource after this time to obtain a fresh URL.
-   `extra_files` (array of PrintFarmDesignFileDto): Supporting files attached to this design (PDFs, manuals, spec sheets). Each entry includes a presigned download URL. Empty when no extras are uploaded. Same shape as `PrintFarmDesignFileDto` above.

**The design object**

```json
{
  "id": "dsg_kP4xT8aBnLf2sH9eY3jZ5dM7cR1vQbWtJ",
  "name": "Dragon Figurine",
  "description": "Articulated dragon, 12cm tall.",
  "color_number": 1,
  "extra_parts": "Two M3 screws and one spring.",
  "extra_parts_config": {},
  "required_filament": false,
  "ams_required": false,
  "assembly": false,
  "farm_instructions": "Print at 0.2mm layer height. Brim recommended.",
  "materials_config": {
    "mode": "single",
    "allowed_materials": [
      {
        "name": "Polymaker Polyterra Cotton White",
        "type": "custom"
      }
    ]
  },
  "hours_multiplier": "1.00",
  "grams_multiplier": "1.00",
  "post_processing_multiplier": "1.00",
  "design_files": [
    {
      "id": "dfl_pL3xB9sK6mT2nH7yC1jZ4dR8vQ5wA9uXkF",
      "file_name": "dragon.3mf",
      "file_type": "model/3mf",
      "size": 524288,
      "download_url": "https://s3.amazonaws.com/...?X-Amz-Signature=...",
      "url_expires_at": "2025-05-20T15:30:00.000Z"
    }
  ],
  "extra_files": [
    {
      "id": "dfl_pL3xB9sK6mT2nH7yC1jZ4dR8vQ5wA9uXkF",
      "file_name": "dragon.3mf",
      "file_type": "model/3mf",
      "size": 524288,
      "download_url": "https://s3.amazonaws.com/...?X-Amz-Signature=...",
      "url_expires_at": "2025-05-20T15:30:00.000Z"
    }
  ]
}
```

## List approved designs visible to your farm

GET `/v1/print-farm/designs`

- **Credentials**: An API key with the `SKU` or `FULL` permission.

- **For**: Print farms

- **Operation id**: `listPrintFarmDesigns`

Returns a paginated list of approved designs reachable from your farm. A design is visible iff it is referenced by a SKU that appears in one of your allocated orders, or in a SKU whose stock is held at one of your farms. Each entry includes a short-lived presigned URL for downloading the design file. Requires an API key with the `SKU` (or `FULL`) permission scope.

### Query parameters

-   `page` (integer): 1-based page index.
    
    Range at least 1. Defaults to 1.
    
-   `page_size` (integer): Page size (max 100).
    
    Range 1 to 100. Defaults to 20.
    
-   `id` (array of string): Filter by design id. Accepts a comma-separated list of UUIDs.
-   `name` (string): Filter by design name (case-insensitive partial match).
-   `ams_required` (boolean): Filter to designs that require (true) or do not require (false) an AMS.
-   `assembly` (boolean): Filter to designs that require (true) or do not require (false) assembly.
-   `required_filament` (boolean): Filter to designs that require (true) or do not require (false) a specific filament.

### Returns 200 OK

Paginated list of approved designs visible to the authenticated farm.

Response attributes (ListPrintFarmDesignsResponseDto):

-   `designs` (array of PrintFarmDesignResponseDto): Approved designs on this page, sorted by creation date (newest first).
    
    Described in [the design object](https://public-api.dapi.digital/docs/reference/print-farm-designs.md#farm_design_object).
    
-   `page` (number): Page number returned, matching the `page` query parameter.
    
    Range at least 1.
    
-   `page_size` (number): Number of items per page, matching the `page_size` query parameter.
    
    Range 1 to 100.
    
-   `total` (number): Total number of approved designs across all pages.
    
    Range at least 0.
    

### Responses

-   `200`: Paginated list of approved designs visible to the authenticated farm.
-   `400`: `page` or `page_size` is outside the allowed range.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have the required permission scope.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the print farm error body](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/print-farm/designs" \
  -H "x-api-key: $DAPI_API_KEY"
```

**Response 200**

```json
{
  "designs": [
    {
      "id": "dsg_kP4xT8aBnLf2sH9eY3jZ5dM7cR1vQbWtJ",
      "name": "Dragon Figurine",
      "description": "Articulated dragon, 12cm tall.",
      "color_number": 1,
      "extra_parts": "Two M3 screws and one spring.",
      "extra_parts_config": {},
      "required_filament": false,
      "ams_required": false,
      "assembly": false,
      "farm_instructions": "Print at 0.2mm layer height. Brim recommended.",
      "materials_config": {
        "mode": "single",
        "allowed_materials": [
          {
            "name": "Polymaker Polyterra Cotton White",
            "type": "custom"
          }
        ]
      },
      "hours_multiplier": "1.00",
      "grams_multiplier": "1.00",
      "post_processing_multiplier": "1.00",
      "design_files": [
        {
          "id": "dfl_pL3xB9sK6mT2nH7yC1jZ4dR8vQ5wA9uXkF",
          "file_name": "dragon.3mf",
          "file_type": "model/3mf",
          "size": 524288,
          "download_url": "https://s3.amazonaws.com/...?X-Amz-Signature=...",
          "url_expires_at": "2025-05-20T15:30:00.000Z"
        }
      ],
      "extra_files": [
        {
          "id": "dfl_pL3xB9sK6mT2nH7yC1jZ4dR8vQ5wA9uXkF",
          "file_name": "dragon.3mf",
          "file_type": "model/3mf",
          "size": 524288,
          "download_url": "https://s3.amazonaws.com/...?X-Amz-Signature=...",
          "url_expires_at": "2025-05-20T15:30:00.000Z"
        }
      ]
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 42
}
```

## Get one approved design visible to your farm

GET `/v1/print-farm/designs/{id}`

- **Credentials**: An API key with the `SKU` or `FULL` permission.

- **For**: Print farms

- **Operation id**: `getPrintFarmDesign`

Returns the approved design matching the given `id`, scoped to designs reachable from your farm via the SKU graph (orders ∪ stock\_levels), with a short-lived presigned URL for downloading the design file. Requires an API key with the `SKU` (or `FULL`) permission scope.

### Path parameters

-   `id` (string, required): The public design identifier (`dsg_…`) returned by the list endpoint.

### Returns 200 OK

The requested design. Returns [the design object](https://public-api.dapi.digital/docs/reference/print-farm-designs.md#farm_design_object).

### Responses

-   `200`: The requested design.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have the required permission scope.
-   `404`: No approved design with this `id` is visible to your farm (it may exist in the catalog but isn't reachable via any of your orders or stock\_levels).
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the print farm error body](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/print-farm/designs/dsg_kP4xT8aBnLf2sH9eY3jZ5dM7cR1vQbWtJ" \
  -H "x-api-key: $DAPI_API_KEY"
```

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/reference/print-farm-designs. Index of every page: https://public-api.dapi.digital/docs/llms.txt.
