---
title: "Delete Agent Definition"
method: DELETE
path: "/api/v1/agent-definitions/{definition_id}"
tags: ["authed"]
---

# Delete Agent Definition

`DELETE /api/v1/agent-definitions/{definition_id}`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/agent-definitions/{definition_id}`
- Auth: none declared

Soft delete: the definition keeps its publish pointer and revisions,
every live read — resolution included — stops seeing it, and its slug
is freed for the living immediately. Active publishable keys pointing
here are repointed at the org's default assistant (cleared when this
IS the assistant, which also strands keyless serving surfaces), and a
Slack agent is disconnected from Slack — so while any of those
consumers exists, the delete answers a 409 naming them until the caller
repeats it with confirm=true.

## Path parameters

- `definition_id` string, uuid, required

## Query parameters

- `confirm` boolean

## Response `204`

Successful Response

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: Active keys select this agent, it is the org-default assistant, or it is installed in Slack, and the delete was not confirmed
- `422`: Validation error
- `500`: Internal server error

## Changes

- **2026-11-03** `c6ac9fd6657f`: 7 info
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `401`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `403`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `404`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `405`
  - …3 more

[Operation history](https://skmtc.dev/teaflask/apis/teaflask-api/changes/api/v1/agent-definitions/:definition_id/delete.md)

---

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