---
title: "Create a reply handler"
method: POST
path: "/v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers"
tags: ["AI SDR Knowledge Bases"]
---

# Create a reply handler

`POST /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers`

<Info>
  **Beta.** This endpoint is in beta. Behavior, parameters, and response shapes may change without notice.
</Info>

<small>_Requires the `ai-sdr:write` scope (or a broader one that includes it)._</small>

Creates a new reply handler attached to a knowledge base.

Requires the AI SDR feature on the caller's team.

## Path parameters

- `knowledge_base_id` integer, required

## Request body

- object — Request body for creating a new reply handler.
  - `typeOfQuestion` string, required — Short label describing the type of incoming reply this handler covers
  - `instructions` string, required — Instructions for how to handle replies of this type
  - `sampleAnswer` string — Optional sample answer used as a few-shot example
  - `toneOfVoice` 'confident' | 'persuasive' | 'witty' | 'straightforward' | 'empathetic' — Tone applied to generated replies and reengagement messages.
  - `responseLength` 'superShort' | 'short' | 'medium' | 'long' — Target length of generated replies and reengagement messages.
  - `links` string[] — Reference URLs (max 10; each non-empty, max 256 chars)
  - `deliveryMode` 'draft' | 'auto' | 'stopAndNotify' — How generated replies for this handler are delivered. Defaults to `draft` when omitted.
  - `additionalNotificationEmail` string, email, nullable — Extra recipient notified when a reply is handled with `stopAndNotify`. Ignored for other delivery modes.

## Response `201`

Reply handler created successfully

- object — Detailed representation of a reply handler.
  - `id` string, uuid — Unique identifier for the reply handler
  - `typeOfQuestion` string — Short label describing the type of incoming reply this handler covers
  - `instructions` string — Instructions for how to handle replies of this type
  - `sampleAnswer` string — Optional sample answer used as a few-shot example
  - `toneOfVoice` 'confident' | 'persuasive' | 'witty' | 'straightforward' | 'empathetic' — Tone applied to generated replies
  - `responseLength` 'superShort' | 'short' | 'medium' | 'long' — Target length for generated replies
  - `links` string[] — Reference URLs the AI SDR can quote when generating a reply
  - `media` object[] — Media items attached to this reply handler. Managed via the `/media` sub-resource.
    - `id` integer — Unique identifier for the media item
    - `fileName` string — Original name of the uploaded file
    - `size` integer — Size in kilobytes
  - `deliveryMode` 'draft' | 'auto' | 'stopAndNotify' — How generated replies for this handler are delivered
  - `additionalNotificationEmail` string, nullable — Extra recipient notified when a reply is handled with `stopAndNotify`. Ignored for other delivery modes.
  - `createdAt` string, date-time — Timestamp when the reply handler was created

## Other responses

- `400` — Validation failure
- `401` — Unauthorized. The response body is empty; check the `WWW-Authenticate` header for the expected scheme.
- `403` — AI SDR feature is not available, or the `stopAndNotify` delivery mode is not enabled for the caller's team
- `404` — Knowledge base not found
- `502` — Upstream AI SDR service failure

---

[API](https://skmtc.net/reply/apis/reply-api.md) · [All operations](https://skmtc.net/reply/apis/reply-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/reply/reply-api/revisions/1c3d32eaf95e/schema)