> ## Documentation Index
> Fetch the complete documentation index at: https://kardow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> List and create job categories, and assign them when posting jobs

Categories group jobs on your board. You can list them, create them, nest them as sub-categories, and assign a category when creating a job, all by name (no need to track UUIDs).

<Info>
  Authenticate with your API key in the `x-api-key` header.
</Info>

## List categories

```http theme={null}
GET https://api.kardow.com/categories
```

```bash cURL theme={null}
curl --url "https://api.kardow.com/categories" \
  --header "x-api-key: your-api-key-here"
```

```json theme={null}
{
  "data": [
    { "id": "1f2e...", "name": "Engineering", "slug": "engineering", "parent_id": null },
    { "id": "4b0d...", "name": "Backend", "slug": "backend", "parent_id": "1f2e..." },
    { "id": "9a7c...", "name": "Design", "slug": "design", "parent_id": null }
  ]
}
```

`parent_id` is the main category of a sub-category, or `null` for a main category.

## Create a category

Creating is idempotent: if a category with that name already exists, its id is returned instead of a duplicate.

```http theme={null}
POST https://api.kardow.com/categories
```

<ParamField body="name" type="string" required>Category name, e.g. `Engineering`.</ParamField>
<ParamField body="parent" type="string | null">Optional. The name or id of a main category to file this one under as a sub-category, e.g. `Engineering`. Send `null` to make it a main category again. Leave it out to keep the category where it is.</ParamField>

```bash cURL theme={null}
curl --request POST \
  --url "https://api.kardow.com/categories" \
  --header "Content-Type: application/json" \
  --header "x-api-key: your-api-key-here" \
  --data '{ "name": "Engineering" }'
```

```bash cURL theme={null}
curl --request POST   --url "https://api.kardow.com/categories"   --header "Content-Type: application/json"   --header "x-api-key: your-api-key-here"   --data '{ "name": "Backend", "parent": "Engineering" }'
```

## Sub-categories

A category can sit under one main category (one level deep). Sub-categories keep their own name, slug and landing page, and:

* Filtering by a main category (`?categories=Engineering`) also returns jobs filed under its sub-categories.
* A main category's job count includes its sub-categories' jobs.
* A main category cannot become a sub-category while it has sub-categories of its own.

Board owners can also nest categories in **Settings > Categories**, where Kardow suggests nesting from the names (for example "Content Marketing" under "Marketing").

## Assigning a category to a job

When creating a job with [Create Job](/docs/api-reference/jobs/post-job), pass either:

* `category` — a category **name**. It is matched to an existing category (case-insensitive) or created if new.
* `category_id` — an existing category UUID (takes precedence over `category`).

To list a job under several categories, send `categories` with every name or id, e.g. `"categories": ["Backend", "DevOps"]`. The job shows under each of them, and the main category (the first, unless `category` or `category_id` is sent) is the one shown on its card. On an update, `categories` replaces the job's list; an empty list keeps only the main category.

```bash cURL theme={null}
curl --request POST \
  --url "https://api.kardow.com/jobs" \
  --header "Content-Type: application/json" \
  --header "x-api-key: your-api-key-here" \
  --data '{
    "title": "Senior Engineer",
    "description": "...",
    "company_name": "Acme",
    "category": "Engineering"
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.