# Create a category

Source: https://developers.swell.is/backend-api/categories/create-a-category

Create a new category.

## Arguments

- `name` (string, required): A human-friendly name for the category.
- `active` (boolean): Set `true` to make the category visible to customers in a storefront, otherwise it will be hidden from view. Default: `false`.
- `description` (string): A long-form description of the category, often containing HTML or other markup languages.
- `slug` (string): Unique identifier typically used in URLs. Defaults to `name` converted to lowercase and hyphenated. If the category has a parent, the default slug will be prefixed with the parent slug. Maximum length of 1,000 characters. Default: `{"$formula":"slug(if(parent_id, join('-', parent.name, name), name))"}`.
- `images` (array of object): List of images depicting the category.
  - `id` (objectId, auto): Unique identifier for the object.
  - `caption` (string): A brief description of the image.
  - `file` (object): An object representing the image file.
    - `id` (objectId): Unique identifier for the file.
    - `content_type` (string): MIME content type of the file.
    - `data` (filedata): A reference to the raw file data.
    - `date_uploaded` (date): Date the file was uploaded.
    - `filename` (string): Optional file name.
    - `height` (int): Image height in pixels, if applicable.
    - `length` (int): Size of the file in bytes.
    - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
    - `url` (string): A public URL to reference the file. Updated automatically if file content changes.
    - `width` (int): Image width in pixels, if applicable.
- `meta_description` (string): Page description used for search engine optimization purposes.
- `meta_keywords` (string): Page keywords used for search engine optimization purposes.
- `meta_title` (string): Page title used to override product name in storefronts.
- `parent_id` (objectId): The id of the parent category, if applicable.
- `sort` (int): Position of the category in a list.
- `sorting` (string): Default product sorting is applied when retrieving products using the `category` or `categories` filter. This can be one of the following: `popularity`, `price_asc`, `price_desc`, `date_asc`. `date_desc`. If not specified, products are sorted by their manually defined `sort` value.
- `top_id` (objectId): ID of the top level category in the hierarchy.
- `top` (Category): Expandable link to the top level category.
- `parent` (Category): Expandable link to the parent category, if applicable.
- `children` (Category): Expandable list of child categories.
- `products` (Product): Expandable list of category products.
- `products_indexed` (Product): Expandable list of products as indexed and sorted by their respective position.

## Example request

`POST /categories`

**cURL**

```bash
$ curl https://api.swell.store/categories \
  -u store-id:secret-key \
  -d name=Widgets \
  -d active=true \
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/categories', {
  name: 'Widgets',
  active: true,
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/categories', [
  'name' => 'Widgets',
  'active' => true
]);
```

## Example response

```json
{
  "id": "5ca9871f9b14d199072432a1",
  "active": false,
  "name": "Widgets",
  "slug": "widgets",
  "date_created": "2019-04-01T00:00:00.000Z"
}
```