# Create category

URL: https://docs.dixa.io/openapi/dixa-api/beta/knowledge/postknowledgecategories

Create a knowledge category. Every category belongs to a collection: pass a collection ID as `parentId` to create a top-level category, or a category ID to create a subcategory

## POST /beta/knowledge/categories

- Server: https://dev.dixa.io
- Auth: `Authorization: <API token>` header

### Request example

```bash
curl -X POST 'https://dev.dixa.io/beta/knowledge/categories' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "translations": [
    {
      "languageId": "en",
      "title": "Getting Started"
    }
  ],
  "parentId": "78dfb531-2e1e-4ffc-bd18-fdad68cd2419"
}'
```

### Response examples

#### 200 The created knowledge category

```json
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": {
      "languageId": "en",
      "title": "Getting Started"
    },
    "isDefaultLocation": true,
    "isLocked": false,
    "restrictions": {
      "isRestricted": true,
      "inheritedRestrictions": [
        {
          "fromCollection": "78dfb531-2e1e-4ffc-bd18-fdad68cd2419"
        }
      ]
    },
    "parentCategory": "222e4567-e89b-12d3-a456-426614174111",
    "parentCollections": [
      "78dfb531-2e1e-4ffc-bd18-fdad68cd2419"
    ]
  }
}
```

#### 400

```json
{
  "message": "Decoding failure in request"
}
```

#### 404 An entity in this request could not be found

```json
{
  "message": "The requested resource could not be found"
}
```

#### 500 Internal failure during request processing

```json
{
  "message": "There was an internal server error while processing the request"
}
```

## OpenAPI definition

The operation and the schemas used, from the full spec at https://docs.dixa.io/openapi-specs/dixa-beta.yaml. Request and response examples are above.

```yaml
openapi: 3.0.3
info:
  title: Dixa API
  version: beta
servers:
  - url: https://dev.dixa.io
security:
  - ApiKeyAuth: []
paths:
  /beta/knowledge/categories:
    post:
      tags:
        - Knowledge
      summary: Create category
      description: "Create a knowledge category. Every category belongs to a
        collection: pass a collection ID as `parentId` to create a top-level
        category, or a category ID to create a subcategory"
      operationId: postKnowledgeCategories
      requestBody:
        description: The knowledge category to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateKnowledgeCategoryInput"
        required: true
      responses:
        "200":
          description: The created knowledge category
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateKnowledgeCategoryOutput"
        "400":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
        "404":
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFound"
        "500":
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
      security:
        - ApiKeyAuth:
            - knowledge.content:w
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    CreateKnowledgeCategoryInput:
      title: CreateKnowledgeCategoryInput
      type: object
      required:
        - parentId
      properties:
        translations:
          description: Initial translations for the category
          type: array
          items:
            $ref: "#/components/schemas/CategoryTranslationInput"
        parentId:
          description: ID of the parent. Use a collection ID to create a top-level
            category, or a category ID to create a subcategory
          type: string
    CategoryTranslationInput:
      title: CategoryTranslationInput
      type: object
      required:
        - languageId
        - title
      properties:
        languageId:
          description: ISO language code (e.g. en, da, de)
          type: string
        title:
          description: Title of the translation
          type: string
    CreateKnowledgeCategoryOutput:
      title: CreateKnowledgeCategoryOutput
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/Category"
          description: The created category
    Category:
      title: Category
      type: object
      required:
        - id
        - isLocked
        - restrictions
      properties:
        id:
          description: ID of the category
          type: string
        title:
          $ref: "#/components/schemas/TranslationTitle"
          description: Title of the category in the requested language, or in the default
            language if no language was requested. Empty if the category has no
            translation in the requested language
        isDefaultLocation:
          description: Whether this is the category's default placement. Always `true`, or
            empty if the category has no parent
          type: boolean
        isLocked:
          description: Whether the category is synced from an Elevio workspace import.
            Locked categories cannot be modified (deleted, moved or renamed)
            while the import is active
          type: boolean
        restrictions:
          $ref: "#/components/schemas/Restrictions"
          description: Access restrictions on the category, set directly or inherited from
            its parents
        parentCategory:
          description: ID of the parent category. Empty for a top-level category, whose
            parent is a collection
          type: string
        parentCollections:
          description: IDs of all collections the category belongs to
          type: array
          items:
            type: string
    TranslationTitle:
      title: TranslationTitle
      type: object
      required:
        - languageId
        - title
      properties:
        languageId:
          type: string
        title:
          type: string
    Restrictions:
      title: Restrictions
      type: object
      required:
        - isRestricted
      properties:
        isRestricted:
          description: "Whether a restriction is set directly on this item. The only
            restriction is internal use: the content is available only to
            logged-in users"
          type: boolean
        inheritedRestrictions:
          description: Restrictions inherited from parent collections or categories. When
            several parents have the same restriction, only the top-most parent
            is listed
          type: array
          items:
            $ref: "#/components/schemas/InheritedRestriction"
    InheritedRestriction:
      title: InheritedRestriction
      type: object
      properties:
        fromCollection:
          description: ID of the collection the restriction is inherited from. Empty if it
            comes from a category
          type: string
        fromCategory:
          description: ID of the category the restriction is inherited from. Empty if it
            comes from a collection
          type: string
    BadRequest:
      title: BadRequest
      type: object
      required:
        - message
      properties:
        message:
          type: string
    NotFound:
      title: NotFound
      type: object
      required:
        - message
      properties:
        message:
          type: string
    ServerError:
      title: ServerError
      type: object
      required:
        - message
      properties:
        message:
          type: string
```