# Materials

Materials your SKUs' designs are printed in.

## Endpoints

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

## The material object

### Attributes

-   `id` (string): Opaque public identifier for this material (`mat_` prefix + 33 base62 chars). Use this value verbatim when referencing the material in other endpoints.
-   `name` (string): Display name of the material.
-   `type` (string): Filament family (e.g. PLA, PETG, ABS).
-   `color` (object, optional): Optional colour hint, free-text or hex.

**The material object**

```json
{
  "id": "mat_jR6tN9pXq4sL8mB3dK7vH2cF5wYzA1ePsK",
  "name": "Polymaker Polyterra Cotton White",
  "type": "PLA",
  "color": "#FFFFFF"
}
```

## List materials visible to your farm

GET `/v1/print-farm/materials`

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

- **For**: Print farms

- **Operation id**: `listPrintFarmMaterials`

Returns a paginated list of materials reachable from your farm, sorted by name. A material is visible iff it is referenced as a `default`\-type entry in `skus.design_list[].materials[]` of a SKU that appears in one of your allocated orders, or in a SKU whose stock is held at one of your farms. Materials outside that chain are not returned. 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` (string): Filter by material id. Accepts a comma-separated list of UUIDs.
-   `name` (string): Filter by material name (case-insensitive partial match).
-   `type` (string): Filter by material type (case-insensitive partial match).

### Returns 200 OK

Paginated list of materials visible to the authenticated farm.

Response attributes (ListPrintFarmMaterialsResponseDto):

-   `materials` (array of PrintFarmMaterialResponseDto): Materials on this page, sorted by name (ascending).
    
    Described in [the material object](https://public-api.dapi.digital/docs/reference/print-farm-materials.md#farm_material_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 materials across all pages (after filters are applied).
    
    Range at least 0.
    

### Responses

-   `200`: Paginated list of materials 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/materials" \
  -H "x-api-key: $DAPI_API_KEY"
```

**Response 200**

```json
{
  "materials": [
    {
      "id": "mat_jR6tN9pXq4sL8mB3dK7vH2cF5wYzA1ePsK",
      "name": "Polymaker Polyterra Cotton White",
      "type": "PLA",
      "color": "#FFFFFF"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 42
}
```

## Get one material visible to your farm

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

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

- **For**: Print farms

- **Operation id**: `getPrintFarmMaterial`

Returns the material matching the given `id`, scoped to materials reachable from your farm via the SKU graph (orders ∪ stock\_levels). Requires an API key with the `SKU` (or `FULL`) permission scope.

### Path parameters

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

### Returns 200 OK

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

### Responses

-   `200`: The requested material.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have the required permission scope.
-   `404`: No material with this `id` is visible to your farm (it may exist in the catalog but isn't referenced via any SKU reachable through 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/materials/mat_jR6tN9pXq4sL8mB3dK7vH2cF5wYzA1ePsK" \
  -H "x-api-key: $DAPI_API_KEY"
```

---

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