Integration Categories

API for managing integration template 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

GET http://[API-URL]/categories

Get all categories. Available to all authenticated users.

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

200: OK

[
  {
    "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
  }
]

Get Category

GET http://[API-URL]/categories/:categoryId

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

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

200: OK

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

404: Not Found

Create Category

POST http://[API-URL]/categories

Create a new category. Admin token required.

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*	string	Category name (1-100 characters), must be unique
description	string	Category description (max 500 characters)

201: Created

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

400: Bad Request - Duplicate Name

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.

Update Category

PUT http://[API-URL]/categories/:categoryId

Update an existing category. Admin token required.

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)

200: OK

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

400: Bad Request - Duplicate Name

404: Not Found

Delete Category

DELETE http://[API-URL]/categories/:categoryId

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

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

200: OK

{
  "success": true
}

404: Not Found

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.

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

POST http://[API-URL]/flows

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

PUT http://[API-URL]/flows/:flowId

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

GET http://[API-URL]/flows/:flowId

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

200: OK

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

Category Restrictions

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.

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

# 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"]
  }'

400: Bad Request

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

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

# 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 documentation for more information.