# Categories

API for managing Categories

## List Categories

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/categories/:app_id`

This endpoint **returns** a list of all `categories` that belong to the publication

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Business",
  "color": "#444444",
  "position": 0
}
```

{% endtab %}
{% endtabs %}

## Get Category

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/categories/:app_id/:id`

This endpoint **returns** a specific `category` by `id`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Category ID                                     |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Business",
  "color": "#444444",
  "position": 0
}
```

{% endtab %}
{% endtabs %}

## Sort Categories

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/categories/:app_id/sort`

This endpoint **sorts** all `categories` by `position` and **returns** an `empty response` with status `204`

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

#### Request Body

| Name                 | Type    | Description |
| -------------------- | ------- | ----------- |
| positions            | Array   |             |
| positions\[id]       | Integer |             |
| positions\[position] | Integer |             |

{% tabs %}
{% tab title="204 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Create Category

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/categories/:app_id`

This endpoint **creates** a new `category` and **returns** the saved `category`

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

#### Request Body

| Name  | Type   | Description             |
| ----- | ------ | ----------------------- |
| title | String | Title of a category     |
| color | String | Hex color of a category |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Business",
  "color": "#444444",
  "position": 0
}
```

{% endtab %}
{% endtabs %}

## Update Category

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/categories/:app_id/:id`

This endpoint **updates** a specific `category` by `id` and **returns** the updated `category`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Category ID                                     |

#### Request Body

| Name  | Type   | Description             |
| ----- | ------ | ----------------------- |
| title | String | Title of a category     |
| color | String | Hex color of a category |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Business",
  "color": "#444444",
  "position": 0
}
```

{% endtab %}
{% endtabs %}

## Delete Category

<mark style="color:red;">`DELETE`</mark> `https://www.magloft.com/api/portal/v1/categories/:app_id/:id`

This endpoint **deletes** a specific `category` by `id` and **returns** an `empty response` with status `204`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Category ID                                     |

{% tabs %}
{% tab title="204 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}