> For the complete documentation index, see [llms.txt](https://docs.simplio3d.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.simplio3d.com/api-reference/open-api/materials/materials.md).

# Materials

API endpoints for managing materials

## <mark style="color:green;">GET</mark> /materials

### Fetch All Materials

#### Endpoint

`GET open-api/v1/materials`

#### Description

This endpoint retrieves a comprehensive list of all available materials in the Simplio3D system.

#### Request

* **Method**: `GET`
* **URL**: `/api/materials`

#### Headers

| Name            | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| `Authorization` | String | Bearer token required for authentication. |

#### Response

* **Status Code**: `200 OK`

**Response Body**

The response will be a JSON object containing the following fields:

| Field       | Type  | Description                   |
| ----------- | ----- | ----------------------------- |
| `materials` | Array | An array of material objects. |

Each material object includes:

| Field  | Type   | Description                         |
| ------ | ------ | ----------------------------------- |
| `id`   | String | Unique identifier for the material. |
| `name` | String | Name of the material.               |

#### Example

```json
{
  "materials": [
  {
    "id": 1,
    "name": "Wood Texture",
    "material_file": "https://example.com/materials/wood.jpg",
    "category_id": 5,
    "texture_id": 2,
    "status": true,
    "material_type": "flat",
    "surface": "smooth",
    "bump": true,
    "color": "#FFFFFF",
    "opacity": 0.8,
    "specular": 0.5,
    "reflection": 0.0,
    "created_at": "2024-02-27T14:23:00Z",
    "updated_at": "2024-02-27T14:23:00Z",
    "created_by": "John Doe"
  }
    },
    {
  {
    "id": 2,
    "name": "Steel",
    "material_file": "https://example.com/materials/steel.jpg",
    "category_id": 5,
    "texture_id": 2,
    "status": true,
    "material_type": "glossy",
    "surface": "smooth",
    "bump": false,
    "color": "#FFFFFF",
    "opacity": 0.8,
    "specular": 0.5,
    "reflection": 0.3,
    "created_at": "2024-02-27T14:23:00Z",
    "updated_at": "2024-02-27T14:23:00Z",
    "created_by": "John Doe"
  }
      }
    }
  ]
}
```

#### Notes

* Ensure the correct authentication token is included in the request header to successfully access the endpoint.
* The properties object can include various attributes specific to the material type.

## Fetch all materials

> Get a list of materials.

```json
{"openapi":"3.0.0","info":{"title":"Simplio3D-Open REST API","version":"1.0.0"},"tags":[{"name":"Materials","description":"API Endpoints for managing materials"}],"servers":[{"url":"https://app.simplio3d.com","description":"API Open Base URL"},{"url":""}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter token in format (Bearer <your_token>)"}},"schemas":{"MaterialsResource":{"title":"Materials Resource","description":"Material object representation","properties":{"id":{"description":"Material ID","type":"integer"},"name":{"description":"Material name","type":"string"},"material_file":{"description":"Material file URL","type":"string","format":"uri"},"category_id":{"description":"Material category ID","type":"integer"},"texture_id":{"description":"Texture ID","type":"integer"},"status":{"description":"Material status (active/inactive)","type":"boolean"},"material_type":{"description":"Type of material","type":"string"},"surface":{"description":"Material surface type","type":"string"},"bump":{"description":"Bump mapping enabled","type":"boolean"},"color":{"description":"Material color","type":"string"},"opacity":{"description":"Opacity level","type":"number","format":"float"},"specular":{"description":"Specular reflection","type":"number","format":"float"},"reflection":{"description":"Reflection intensity","type":"number","format":"float"},"created_at":{"description":"Creation date","type":"string","format":"date-time"},"updated_at":{"description":"Last update date","type":"string","format":"date-time"},"created_by":{"description":"User who created the material","type":"string"}},"type":"object"}}},"paths":{"/api/open-api/v1/materials":{"get":{"tags":["Materials"],"summary":"Fetch all materials","description":"Get a list of materials.","operationId":"bf812f0e4532259fa82617dd3e020c84","parameters":[{"name":"per_page","in":"query","description":"Number of items per page (-1 for all)","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Number of page","required":false,"schema":{"type":"integer"}},{"name":"order_by","in":"query","description":"Field to order by","required":false,"schema":{"type":"string"}},{"name":"order","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"category_id","in":"query","description":"Filter materials by category ID","required":false,"schema":{"type":"integer"}},{"name":"texture_id","in":"query","description":"Filter materials by texture ID","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MaterialsResource"}}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}}}}
```

## <mark style="color:green;">GET</mark> /materials/{id}

#### Get Material by ID Endpoint

The `Get Material by ID` endpoint of the Simplio3D API allows you to retrieve detailed information about a specific material by its unique identifier. This endpoint is ideal for applications requiring precise details about materials used in 3D modeling or rendering.

**Endpoint**

```http
GET /open-api/v1/materials/{id}
```

**Path Parameters**

* `id` (integer): The unique identifier of the material to be retrieved.

**Request Headers**

* `Authorization`: Bearer token required to authenticate the request.

**Response**

The response includes the following attributes specific to the requested material:

* `id`: The unique identifier of the material.
* `name`: The name of the material.
* `material_file`: URL to the material's texture file.
* `category_id`: The ID of the category to which the material belongs.
* `texture_id`: The ID of the texture applied to the material.
* `status`: Boolean indicating whether the material is active.
* `material_type`: The type of material (e.g., flat, glossy).
* `surface`: Description of the material's surface finish.
* `bump`: Boolean indicating if the material has bump mapping.
* `color`: Hex color code representing the material's default color.
* `opacity`: The opacity level of the material.
* `specular`: The specular reflection component of the material.
* `reflection`: The reflection intensity of the material.
* `created_at`: ISO 8601 date and time representing when the material was created.
* `updated_at`: ISO 8601 date and time representing the last update.
* `created_by`: The name of the user who created the material.

**Example Request**

```http
GET /open-api/v1/materials/1
Authorization: Bearer {token}
```

**Example Response**

```json
{
  "id": 1,
  "name": "Wood Texture",
  "material_file": "https://example.com/materials/wood.jpg",
  "category_id": 5,
  "texture_id": 2,
  "status": true,
  "material_type": "flat",
  "surface": "smooth",
  "bump": true,
  "color": "#FFFFFF",
  "opacity": 0.8,
  "specular": 0.5,
  "reflection": 0.0,
  "created_at": "2024-02-27T14:23:00Z",
  "updated_at": "2024-02-27T14:23:00Z",
  "created_by": "John Doe"
}
```

**Notes**

* Ensure that the authentication token is valid and correctly included in the headers to access the endpoint successfully.

## Get material by ID

> Get a specific material by ID.

```json
{"openapi":"3.0.0","info":{"title":"Simplio3D-Open REST API","version":"1.0.0"},"tags":[{"name":"Materials","description":"API Endpoints for managing materials"}],"servers":[{"url":"https://app.simplio3d.com","description":"API Open Base URL"},{"url":""}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter token in format (Bearer <your_token>)"}},"schemas":{"MaterialsResource":{"title":"Materials Resource","description":"Material object representation","properties":{"id":{"description":"Material ID","type":"integer"},"name":{"description":"Material name","type":"string"},"material_file":{"description":"Material file URL","type":"string","format":"uri"},"category_id":{"description":"Material category ID","type":"integer"},"texture_id":{"description":"Texture ID","type":"integer"},"status":{"description":"Material status (active/inactive)","type":"boolean"},"material_type":{"description":"Type of material","type":"string"},"surface":{"description":"Material surface type","type":"string"},"bump":{"description":"Bump mapping enabled","type":"boolean"},"color":{"description":"Material color","type":"string"},"opacity":{"description":"Opacity level","type":"number","format":"float"},"specular":{"description":"Specular reflection","type":"number","format":"float"},"reflection":{"description":"Reflection intensity","type":"number","format":"float"},"created_at":{"description":"Creation date","type":"string","format":"date-time"},"updated_at":{"description":"Last update date","type":"string","format":"date-time"},"created_by":{"description":"User who created the material","type":"string"}},"type":"object"}}},"paths":{"/api/open-api/v1/materials/{id}":{"get":{"tags":["Materials"],"summary":"Get material by ID","description":"Get a specific material by ID.","operationId":"c74355fb62a78e298fec06865c3e77dd","parameters":[{"name":"id","in":"path","description":"ID of the material","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialsResource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Material not found"},"500":{"description":"Internal Server Error"}}}}}}
```

## Get list of materials categories (without pagination)

> Get all materials categories without pagination.

```json
{"openapi":"3.0.0","info":{"title":"Simplio3D-Open REST API","version":"1.0.0"},"tags":[{"name":"Materials Categories","description":"API Endpoints for managing materials categories"}],"servers":[{"url":"https://app.simplio3d.com","description":"API Open Base URL"},{"url":""}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter token in format (Bearer <your_token>)"}},"schemas":{"MaterialsCategoriesResource":{"title":"Materials Categories Resource","description":"Materials Categories Model","properties":{"id":{"description":"ID of the material category","type":"integer"},"title":{"description":"Title of the material category","type":"string"},"description":{"description":"Description of the material category","type":"string"},"created_at":{"description":"Timestamp when the material category was created","type":"string","format":"date-time"},"updated_at":{"description":"Timestamp when the material category was last updated","type":"string","format":"date-time"},"created_by":{"description":"Name of the creator","type":"string"}},"type":"object"}}},"paths":{"/api/open-api/v1/materials-categories/list":{"get":{"tags":["Materials Categories"],"summary":"Get list of materials categories (without pagination)","description":"Get all materials categories without pagination.","operationId":"ca6213cfd7e44a2b1c3c09e1a397d2eb","parameters":[{"name":"order_by","in":"query","description":"Column to order the results by (default: created_at)","required":false,"schema":{"type":"string"}},{"name":"order","in":"query","description":"Order direction (asc or desc, default: desc)","required":false,"schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MaterialsCategoriesResource"}}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}}}}
```

## The MaterialsResource object

```json
{"openapi":"3.0.0","info":{"title":"Simplio3D-Open REST API","version":"1.0.0"},"components":{"schemas":{"MaterialsResource":{"title":"Materials Resource","description":"Material object representation","properties":{"id":{"description":"Material ID","type":"integer"},"name":{"description":"Material name","type":"string"},"material_file":{"description":"Material file URL","type":"string","format":"uri"},"category_id":{"description":"Material category ID","type":"integer"},"texture_id":{"description":"Texture ID","type":"integer"},"status":{"description":"Material status (active/inactive)","type":"boolean"},"material_type":{"description":"Type of material","type":"string"},"surface":{"description":"Material surface type","type":"string"},"bump":{"description":"Bump mapping enabled","type":"boolean"},"color":{"description":"Material color","type":"string"},"opacity":{"description":"Opacity level","type":"number","format":"float"},"specular":{"description":"Specular reflection","type":"number","format":"float"},"reflection":{"description":"Reflection intensity","type":"number","format":"float"},"created_at":{"description":"Creation date","type":"string","format":"date-time"},"updated_at":{"description":"Last update date","type":"string","format":"date-time"},"created_by":{"description":"User who created the material","type":"string"}},"type":"object"}}}}
```