---
title: "Create custom category"
method: POST
path: "/signal/custom_categories"
tags: ["signal"]
---

# Create custom category

`POST /signal/custom_categories`

Create a custom fraud category from example phrases. Categories embed asynchronously:
a new category starts at `pending`, moves to `embedding`, and becomes usable for
scoring once its status is `ready`.

## Headers

- `Authorization` string, required

## Request body

- SignalCustomCategoryCreateRequest
  - `name` string, required — Category name. Must be unique within the team.
  - `scenarios` string[], required — Example phrases that define the pattern. Maximum 50 entries, each up to 2000 characters. A newline-separated string is also accepted.
  - `description` string
  - `icon` string — Single emoji.
  - `enabled` boolean

## Response `200`

Category created

- SignalCustomCategoryResponse
  - `success` boolean, required
  - `item` SignalCustomCategory, required
    - `id` integer
    - `name` string
    - `description` string, nullable
    - `icon` string, nullable
    - `enabled` boolean — Whether the category is included in scoring.
    - `status` 'pending' | 'embedding' | 'ready' | 'needs_more_examples' | 'failed'
    - `embed_error` string, nullable — Error message when `status` is `failed`.
    - `embedded_at` string, date-time, nullable
    - `scenario_count` integer
    - `embedding_model_version` string, nullable
    - `overlaps` SignalCustomCategoryOverlapsItems[] — Calibration warnings where this category was confused with another.
    - `scenarios` SignalScenario[]
      - `id` integer
      - `text` string
      - `embedded` boolean — Whether this example has finished embedding.

## Other responses

- `422` — Validation error

---

[API](https://skmtc.dev/resemble/apis/api-reference.md) · [All operations](https://skmtc.dev/resemble/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/resemble/api-reference/revisions/e93597a6b425/schema)