---
title: "Propose a bounded AI edit to the agent's workflow draft"
method: POST
path: "/v1/agents/{agent_id}/workflow/ai-edit"
---

# Propose a bounded AI edit to the agent's workflow draft

`POST /v1/agents/{agent_id}/workflow/ai-edit`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/agents/{agent_id}/workflow/ai-edit`
- Auth: none declared

Given a free-text instruction, asks the AI generation provider to propose a replacement draft, then returns that proposal plus its validation -- it never writes to the draft. AI edits preserve the author's caller-speech listener selection. The caller (frontend) shows a diff and, only on explicit accept, PATCHes the existing update-draft route with the proposal, so an accepted AI edit is undoable through the same history as any manual edit. Rejects a proposal that changes more than 10 steps.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `instruction` string, required

## Response `200`

Proposed draft, its validation, and the changed-step count

## Other responses

- `400`: Missing instruction, the AI generation provider is unavailable/unreadable, or the proposal exceeds the bounded-edit step cap
- `404`: Agent has no workflow yet

---

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