# Integration Categories

Categories allow you to organize integration templates in the Automation Hub marketplace. Each template can be assigned to multiple categories, which can then be used to create custom tabs and filters in the marketplace widget.

## Overview

* Categories are global/system-wide resources
* Admin-only access for create/update/delete operations
* All authenticated users can read categories
* Templates can belong to multiple categories
* Only integration templates and drafts can have categories
* Deleting a category removes it from all associated templates

## List Categories

<mark style="color:blue;">`GET`</mark> `http://[API-URL]/categories`

Get all categories. Available to all authenticated users.

```bash
curl -XGET "http://[API-URL]/categories" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"
```

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

```javascript
[
  {
    "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
    "name": "CRM",
    "description": "Customer relationship management integrations",
    "created": 1678901234567,
    "mtime": 1678901234567
  },
  {
    "id": "5f8a7b2c3d4e5f6a7b8c9d0f",
    "name": "Marketing",
    "description": "Marketing automation and analytics tools",
    "created": 1678901234568,
    "mtime": 1678901234568
  }
]
```

{% endtab %}
{% endtabs %}

## Get Category

<mark style="color:blue;">`GET`</mark> `http://[API-URL]/categories/:categoryId`

Get details of a specific category. Available to all authenticated users.

```bash
curl -XGET "http://[API-URL]/categories/5f8a7b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"
```

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

```javascript
{
  "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
  "name": "CRM",
  "description": "Customer relationship management integrations",
  "created": 1678901234567,
  "mtime": 1678901234567
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Create Category

<mark style="color:green;">`POST`</mark> `http://[API-URL]/categories`

Create a new category. Admin token required.

```bash
curl -XPOST "http://[API-URL]/categories" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{ "name": "CRM", "description": "Customer relationship management integrations" }'
```

#### Request Body

| Name                                   | Type   | Description                                      |
| -------------------------------------- | ------ | ------------------------------------------------ |
| name<mark style="color:red;">\*</mark> | string | Category name (1-100 characters), must be unique |
| description                            | string | Category description (max 500 characters)        |

{% tabs %}
{% tab title="201: Created" %}

```javascript
{
  "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
  "name": "CRM",
  "description": "Customer relationship management integrations",
  "created": 1678901234567,
  "mtime": 1678901234567
}
```

{% endtab %}

{% tab title="400: Bad Request - Duplicate Name" %}

```javascript
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Category with this name already exists."
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Unique Names**

Category names must be unique across the system. If you attempt to create a category with a name that already exists, the API will return a 400 Bad Request error.
{% endhint %}

## Update Category

<mark style="color:orange;">`PUT`</mark> `http://[API-URL]/categories/:categoryId`

Update an existing category. Admin token required.

```bash
curl -XPUT "http://[API-URL]/categories/5f8a7b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{ "name": "CRM & Sales", "description": "Customer relationship management and sales tools" }'
```

#### Request Body

| Name        | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| name        | string | Updated category name (1-100 characters) |
| description | string | Updated description (max 500 characters) |

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

```javascript
{
  "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
  "name": "CRM & Sales",
  "description": "Customer relationship management and sales tools",
  "created": 1678901234567,
  "mtime": 1678905678901
}
```

{% endtab %}

{% tab title="400: Bad Request - Duplicate Name" %}

```javascript
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Category with this name already exists."
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```javascript
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Category not found."
}
```

{% endtab %}
{% endtabs %}

## Delete Category

<mark style="color:red;">`DELETE`</mark> `http://[API-URL]/categories/:categoryId`

Delete a category. Admin token required. This will automatically remove the category from all templates that reference it.

```bash
curl -XDELETE "http://[API-URL]/categories/5f8a7b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer [ADMIN_TOKEN]"
```

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

```javascript
{
  "success": true
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```javascript
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Category not found."
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Automatic Cleanup**

When a category is deleted, it is automatically removed from all integration templates and drafts that reference it. This ensures data consistency without requiring manual cleanup.
{% endhint %}

## Assigning Categories to Templates

Categories are assigned to integration templates through the Flow API. When creating or updating a flow, you can specify categories in the `categories` array.

### Create Flow with Categories

<mark style="color:green;">`POST`</mark> `http://[API-URL]/flows`

```bash
curl -XPOST "http://[API-URL]/flows" \
  -H "Authorization: Bearer [ACCESS_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "Salesforce to HubSpot Sync",
    "type": "integration-template",
    "categories": ["5f8a7b2c3d4e5f6a7b8c9d0e", "5f8a7b2c3d4e5f6a7b8c9d0f"],
    "flow": { ... }
  }'
```

### Update Flow Categories

<mark style="color:orange;">`PUT`</mark> `http://[API-URL]/flows/:flowId`

```bash
curl -XPUT "http://[API-URL]/flows/[FLOW_ID]" \
  -H "Authorization: Bearer [ACCESS_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "categories": ["5f8a7b2c3d4e5f6a7b8c9d0e"]
  }'
```

### Get Flow with Categories

<mark style="color:blue;">`GET`</mark> `http://[API-URL]/flows/:flowId`

```bash
curl -XGET "http://[API-URL]/flows/[FLOW_ID]" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"
```

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

```javascript
{
  "id": "796d7b5c-bea0-4594-a9df-a8a0e3c4616e",
  "name": "Salesforce to HubSpot Sync",
  "type": "integration-template",
  "categories": ["5f8a7b2c3d4e5f6a7b8c9d0e", "5f8a7b2c3d4e5f6a7b8c9d0f"],
  "flow": { ... },
  ...
}
```

{% endtab %}
{% endtabs %}

## Category Restrictions

{% hint style="warning" %}
**Flow Type Restrictions**

Categories can only be assigned to:

* Integration templates (`integration-template`)
* Integration drafts (`integration-draft`)

Attempting to assign categories to other flow types (e.g., `flow`, `flow-template`) will result in a 400 Bad Request error.
{% endhint %}

## Category Validation

When assigning categories to a template, the API validates:

1. **Category Existence**: All category IDs must reference existing categories
2. **Flow Type**: The flow must be an integration template or draft
3. **Array Format**: Categories must be provided as an array of category IDs

### Validation Example

```bash
# Invalid - category doesn't exist
curl -XPOST "http://[API-URL]/flows" \
  -H "Authorization: Bearer [ACCESS_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "My Template",
    "type": "integration-template",
    "categories": ["invalid-category-id"]
  }'
```

{% tabs %}
{% tab title="400: Bad Request" %}

```javascript
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Category with ID invalid-category-id does not exist."
}
```

{% endtab %}
{% endtabs %}

## Use Cases

### Marketplace Organization

Categories are primarily used to organize templates in the Automation Hub marketplace:

1. **Create categories** for your use cases (CRM, Marketing, Finance, etc.)
2. **Assign templates** to relevant categories
3. **Configure marketplace tabs** in Hub Settings to display templates by category
4. **End users browse** templates organized by category in the marketplace widget

### Example Workflow

```bash
# 1. Create categories
curl -XPOST "http://[API-URL]/categories" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{ "name": "CRM", "description": "CRM integrations" }'

# Response: { "id": "cat-crm-123", ... }

curl -XPOST "http://[API-URL]/categories" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{ "name": "Marketing", "description": "Marketing tools" }'

# Response: { "id": "cat-marketing-456", ... }

# 2. Assign template to categories
curl -XPUT "http://[API-URL]/flows/my-template-id" \
  -H "Authorization: Bearer [ACCESS_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{ "categories": ["cat-crm-123", "cat-marketing-456"] }'

# 3. End users see the template in both CRM and Marketing tabs
```

## Audit Logging

All category operations are automatically logged in the audit trail:

* **Create**: `"Create category: [name]"`
* **Update**: `"Update category: [name]"`
* **Delete**: `"Delete category: [name]"`

Each log entry includes:

* Operation type (create/update/delete)
* Before and after state (for updates)
* Timestamp and performing user

See the [Audit Logs](/appmixer-backoffice/audit-logs.md) documentation for more information.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appmixer.com/api/integration-categories.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.