---
title: "Stage Agent Draft"
method: POST
path: "/v1/draft-authoring/orgs/{org_id}/agents"
tags: ["draft-authoring"]
---

# Stage Agent Draft

`POST /v1/draft-authoring/orgs/{org_id}/agents`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v1/draft-authoring/orgs/{org_id}/agents`
- Auth: none declared

A new agent as a draft, or, with ``agent_id``, the draft of that live agent.

A live agent has one draft; posting again rewrites it. The live agent and its tool
bindings are untouched until a person publishes. A new agent exists only once a person
opens the returned link and creates it.

## Path parameters

- `org_id` string, uuid, required

## Query parameters

- `workspace_id` string, uuid, nullable

## Request body

- DraftAuthoringAgentCreate
  - `yaml_content` string, required: The agent.yaml, as the agent editor stores it
  - `agent_id` string, uuid, nullable: A live agent to change; omit for a new agent

## Response `201`

Successful Response

- DraftAuthoringAgentOut
  - `id` string, uuid, required: The draft's id
  - `draft_of_id` string, uuid, nullable: The live agent publishing this draft updates
  - `review_url` string, required: Where a person reviews and publishes (or creates) the agent

## Other responses

- `422`: Validation Error

---

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