---
title: "Create a classifier"
method: POST
path: "/classifiers"
tags: ["Gateway"]
---

# Create a classifier

`POST /classifiers`

## Request

- Base URL: `https://api.phaseo.app/v1`
- URL: `https://api.phaseo.app/v1/classifiers`
- Auth: HTTP bearer

Creates a classifier. After each eligible request finishes, the chosen model places it in every dimension and the answers are added to the request as labels, so they can be filtered and grouped in logs, usage and analytics. Classification runs after the response is sent and is billed to the workspace at the model's normal price.

## Request body

- ClassifierCreateInput
  - `name` string, required
  - `description` string, nullable
  - `enabled` boolean
  - `model` string, required
  - `instructions` string
  - `dimensions` ClassifierDimension[], required
    - `key` string, required
    - `name` string
    - `description` string, nullable
    - `multiple` boolean: Allow more than one value per request.
    - `allow_other` boolean: Let the model answer "other" when no listed value fits.
    - `values` ClassifierValue[], required: Between 2 and 50 values. A single value is allowed only when allow_other is true.
      - `value` string, required
      - `description` string, nullable: Tells the model when to pick this value.
  - `sample_rate` number, double
  - `sample_by` 'request' | 'session': request samples each request on its own. session keeps every request in a session in or out together.
  - `input_scope` 'prompt' | 'prompt_and_response': prompt classifies the request messages. prompt_and_response also shows the model the generated response.
  - `scope` ClassifierScope: Limits which requests are classified. Leave a list out to include everything.
    - `key_ids` string[]
    - `app_ids` string[]
    - `models` string[]
  - `monthly_budget_usd` number, double, nullable

## Response `201`

Classifier created

- ClassifierResponse
  - `data` Classifier, required: A workspace taxonomy that a chosen model applies to requests after they finish.
    - `id` string, uuid, required
    - `workspace_id` string, uuid, required
    - `name` string, required
    - `description` string, nullable, required
    - `enabled` boolean, required
    - `model` string, required: Model that classifies requests, for example google/gemini-2.5-flash-lite.
    - `instructions` string, required: Extra guidance for the model, added to the classification prompt.
    - `dimensions` ClassifierDimension[], required
      - `key` string, required
      - `name` string
      - `description` string, nullable
      - `multiple` boolean: Allow more than one value per request.
      - `allow_other` boolean: Let the model answer "other" when no listed value fits.
      - `values` ClassifierValue[], required: Between 2 and 50 values. A single value is allowed only when allow_other is true.
        - `value` string, required
        - `description` string, nullable: Tells the model when to pick this value.
    - `sample_rate` number, double, required: Share of eligible requests to classify. 1 classifies every request.
    - `sample_by` 'request' | 'session', required: request samples each request on its own. session keeps every request in a session in or out together.
    - `input_scope` 'prompt' | 'prompt_and_response', required: prompt classifies the request messages. prompt_and_response also shows the model the generated response.
    - `scope` ClassifierScope, required: Limits which requests are classified. Leave a list out to include everything.
      - `key_ids` string[]
      - `app_ids` string[]
      - `models` string[]
    - `monthly_budget_usd` number, double, nullable, required: Most the classifier may spend in a UTC calendar month. Classification pauses for the rest of the month once it is reached. null means no cap.
    - `created_by` string, uuid, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `default`: Request failed

## Changes

- **2026-10-21** `f2a7a9f9a8e2`: 1 breaking, 2 info
  - added `#/components/schemas/ErrorObject` to the `error` response property `oneOf` list for the response status `default`
  - added the optional property `code` to the response with the `default` status
  - removed `subschema #2` from the `error` response property `oneOf` list for the response status `default`
- **2026-10-20** `1d0e000a9005`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/phaseo/apis/phaseo-gateway-api/changes/classifiers/post.md)

---

[API](https://skmtc.dev/phaseo/apis/phaseo-gateway-api.md) - [All operations](https://skmtc.dev/phaseo/apis/phaseo-gateway-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phaseo/apis/phaseo-gateway-api/revisions/5ca9bb220d25?raw)