# Materials

The material catalog.

## Endpoints

-   [GET `/v2/materials`](https://public-api.dapi.digital/docs/reference/materials.md#list_materials)
-   [GET `/v2/materials/{id}`](https://public-api.dapi.digital/docs/reference/materials.md#get_material)

## The material object

A material a design can be printed in, either from the 3DAPI catalog or custom.

### Attributes

-   `id` (string or null): Unique identifier of a catalog material, prefixed with `mat_`. Null for a custom material.
-   `object` (string): Names the type of this object. Always `material`.
-   `name` (string): Display name, for example `PLA Black`. For custom materials, exactly what the seller typed.
-   `custom` (boolean): True for a seller-specified material that is not in the catalog. Custom materials need manual review before production.
-   `technology` (string or null): Printing technology. `fdm` is filament printing, the only one offered today. Null for custom materials.
-   `color` (string or null): Color name as listed in the catalog, for example `Black`. Null for custom materials.
-   `color_hex` (string or null): Reference colour of the filament as `#RRGGBB`, the colour 3DAPI matches the colours in your 3MF files against (see `suggested_materials` on a quote). Null for custom materials and catalog materials without a reference colour.
-   `filament_type` (string or null): Plastic family in lowercase, for example `pla` or `petg`. Null for custom materials and when unknown.

**The material object**

```json
{
  "id": "mat_bfP0GSqKoZFrD72H5Os0rc7HV9XP6eQJu",
  "object": "material",
  "name": "PLA Black",
  "custom": false,
  "technology": "fdm",
  "color": "Black",
  "color_hex": "#000000",
  "filament_type": "pla"
}
```

## List catalog materials

GET `/v2/materials`

Public: no API key needed.

- **Credentials**: None: the endpoint is public.

- **For**: Designers and Integrators

- **Operation id**: `list_materials`

Lists every material in the 3DAPI catalog, the materials a design can be printed in. Public: no credentials needed. Use the ids when configuring which materials a design allows.

### Query parameters

-   `limit` (integer): How many results per page, from 1 to 100.
    
    Range 1 to 100. Defaults to 20.
    
-   `cursor` (string): Where to continue from: the `next_cursor` of the previous page. Omit for the first page.

### Returns 200 OK

A page of catalog materials.

Response attributes (MaterialList):

-   `object` (string): Names the type of this object. Always `list`.
-   `data` (array of Material): The page of results.
    
    Described in [the material object](https://public-api.dapi.digital/docs/reference/materials.md#material_object).
    
-   `has_more` (boolean): True when more results exist after this page. Fetch them by passing `next_cursor` as `cursor`.
-   `next_cursor` (string or null): Opaque cursor for the next page, or null on the last page. Pass it back unchanged as `cursor`.

### Responses

-   `200`: A page of catalog materials.
-   `400`: The request is invalid. `details.errors` lists each problem (`validation_failed`), or an `expand[]` path is unknown (`invalid_expand`).
-   `429`: Too many requests (`rate_limited`): the limit is 120 per minute per IP address. Wait for the number of seconds in the `Retry-After` header, then retry; `details` has `limit`, `window_seconds`, `reset_at` and `retry_after_seconds`.

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

**Request**

```bash
curl "https://public-api.dapi.digital/v2/materials"
```

**Response 200**

```json
{
  "object": "list",
  "data": [
    {
      "id": "mat_bfP0GSqKoZFrD72H5Os0rc7HV9XP6eQJu",
      "object": "material",
      "name": "PLA Black",
      "custom": false,
      "technology": "fdm",
      "color": "Black",
      "color_hex": "#000000",
      "filament_type": "pla"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Get a catalog material

GET `/v2/materials/{id}`

Public: no API key needed.

- **Credentials**: None: the endpoint is public.

- **For**: Designers and Integrators

- **Operation id**: `get_material`

Returns one catalog material by id. Public: no credentials needed.

### Path parameters

-   `id` (string, required): Unique identifier of the material, prefixed with `mat_`. Treat it as an opaque string: store it and compare it, never parse it.

### Returns 200 OK

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

### Responses

-   `200`: The material.
-   `404`: No catalog material has this id (`material_not_found`).
-   `429`: Too many requests (`rate_limited`): the limit is 120 per minute per IP address. Wait for the number of seconds in the `Retry-After` header, then retry; `details` has `limit`, `window_seconds`, `reset_at` and `retry_after_seconds`.

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

**Request**

```bash
curl "https://public-api.dapi.digital/v2/materials/mat_bfP0GSqKoZFrD72H5Os0rc7HV9XP6eQJu"
```

---

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