Agent Drafts

Create, iterate, and publish agent drafts. A draft is a workspace with a linear version chain — each save creates a new immutable version snapshot. When a version is ready, publish it to create a live agent. Draft summaries expose name from the head version's agent_name; there is no separate draft-level name. Empty agent names display as Untitled Draft. Version titles default to sequential labels (v1, v2, …) from a monotonic counter; renaming a version sets a custom title without affecting it.

List drafts

GET

/v1/agent-drafts

Draft summaries visible to the caller. Pass mine=true for the library
view: only the caller's own. name comes from the head version's
agent_name; an empty name displays as Untitled Draft.

Pass tags (repeatable) to keep only drafts whose head version carries every
given tag; tags=tool lists tool-agent drafts. Pass exclude_tags (repeatable)
to leave out drafts whose head version carries any given tag; exclude_tags=tool
lists chat-agent drafts. Both combine, and total counts the filtered set.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Query Parameters

mine

Type

boolean

Default

false

tags

Keep drafts whose head version has all of these tags.

exclude_tags

Leave out drafts whose head version has any of these tags.

Responses

Successful Response

Content-Type

application/json

{

  

"items": [

  

  

{

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"created_by_name": "string",

  

  

  

"head_version_id": "string",

  

  

  

"id": "string",

  

  

  

"name": "string",

  

  

  

"next_version_number": 0,

  

  

  

"org_id": "string",

  

  

  

"tags": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"team_ids": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"updated_at": "string",

  

  

  

"visibility": "string"

  

  

}

  

],

  

"total": 0

}

Samples

Create a draft

POST

/v1/agent-drafts

Creates a draft workspace with an initial version. Set source_agent_id to seed from a published agent, source_version_id to seed from an existing version, or omit both for a blank draft.

Set tool_agent on a blank draft to build a tool agent: it is tagged tool, may enable tools, and has no anchor words. A chat agent (the default) may not enable tools. The kind is fixed at creation; a copy keeps its source's kind.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Request Body

application/json

Unified creation body.

Omit both source fields for a blank draft.
Set source_agent_id to fork from a published agent.
Set source_version_id to fork from an existing draft version.

Default""

Default""

Any of

Any of

Any of

Default""

Any of

Any of

Default4096

Any of

Format"uuid"

Any of

Format"uuid"

Format"uuid"

Default0.7

Create a tool agent: equipment a workflow step calls, with tools and no chat page. Fixed at creation and never changed afterwards. Omit when copying from source_agent_id or source_version_id: the copy keeps its source's kind, and a value that disagrees is refused with 422.

Defaultfalse

Valid values"personal""team_level""org_level""community""universal"

Default"personal"

Responses

Successful Response

Content-Type

application/json

{

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"head_version_id": "string",

  

"id": "string",

  

"name": "string",

  

"next_version_number": 0,

  

"notice": "string",

  

"org_id": "string",

  

"tags": [

  

  

"string"

  

],

  

"team_ids": [

  

  

"string"

  

],

  

"updated_at": "string",

  

"versions": [

  

  

{

  

  

  

"agent_name": "string",

  

  

  

"agent_prompt": "string",

  

  

  

"anchor_word_count": 0,

  

  

  

"anchor_words": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"anchor_words_ready": false,

  

  

  

"chat_model": "string",

  

  

  

"color": "string",

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"description": "",

  

  

  

"draft_id": "string",

  

  

  

"embedding_status": "string",

  

  

  

"enabled_tools": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"eval_scores": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"eval_status": "string",

  

  

  

"golden_cases": [

  

  

  

  

{

  

  

  

  

  

"additionalProperties": "string"

  

  

  

  

}

  

  

  

],

  

  

  

"icon_name": "string",

  

  

  

"id": "string",

  

  

  

"max_tokens": 0,

  

  

  

"parent_version_id": "string",

  

  

  

"tags": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"temperature": 0,

  

  

  

"title": "string"

  

  

}

  

],

  

"visibility": "string"

}

Samples

Delete a draft and all its versions

DELETE

/v1/agent-drafts/{draft_id}

Delete a draft and every version in its chain.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Samples

Get a draft

GET

/v1/agent-drafts/{draft_id}

Get a draft with its full version chain, oldest first.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"head_version_id": "string",

  

"id": "string",

  

"name": "string",

  

"next_version_number": 0,

  

"notice": "string",

  

"org_id": "string",

  

"tags": [

  

  

"string"

  

],

  

"team_ids": [

  

  

"string"

  

],

  

"updated_at": "string",

  

"versions": [

  

  

{

  

  

  

"agent_name": "string",

  

  

  

"agent_prompt": "string",

  

  

  

"anchor_word_count": 0,

  

  

  

"anchor_words": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"anchor_words_ready": false,

  

  

  

"chat_model": "string",

  

  

  

"color": "string",

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"description": "",

  

  

  

"draft_id": "string",

  

  

  

"embedding_status": "string",

  

  

  

"enabled_tools": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"eval_scores": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"eval_status": "string",

  

  

  

"golden_cases": [

  

  

  

  

{

  

  

  

  

  

"additionalProperties": "string"

  

  

  

  

}

  

  

  

],

  

  

  

"icon_name": "string",

  

  

  

"id": "string",

  

  

  

"max_tokens": 0,

  

  

  

"parent_version_id": "string",

  

  

  

"tags": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"temperature": 0,

  

  

  

"title": "string"

  

  

}

  

],

  

"visibility": "string"

}

Samples

Update a draft

PATCH

/v1/agent-drafts/{draft_id}

Visibility and team membership apply to the whole draft workspace, not individual versions. Omitted fields are left unchanged.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Draft-level visibility — shared by every version in the workspace.

Any of

Format"uuid"

Any of

Valid values"personal""team_level""org_level""community""universal"

Responses

Successful Response

Content-Type

application/json

{

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"head_version_id": "string",

  

"id": "string",

  

"name": "string",

  

"next_version_number": 0,

  

"notice": "string",

  

"org_id": "string",

  

"tags": [

  

  

"string"

  

],

  

"team_ids": [

  

  

"string"

  

],

  

"updated_at": "string",

  

"versions": [

  

  

{

  

  

  

"agent_name": "string",

  

  

  

"agent_prompt": "string",

  

  

  

"anchor_word_count": 0,

  

  

  

"anchor_words": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"anchor_words_ready": false,

  

  

  

"chat_model": "string",

  

  

  

"color": "string",

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"description": "",

  

  

  

"draft_id": "string",

  

  

  

"embedding_status": "string",

  

  

  

"enabled_tools": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"eval_scores": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"eval_status": "string",

  

  

  

"golden_cases": [

  

  

  

  

{

  

  

  

  

  

"additionalProperties": "string"

  

  

  

  

}

  

  

  

],

  

  

  

"icon_name": "string",

  

  

  

"id": "string",

  

  

  

"max_tokens": 0,

  

  

  

"parent_version_id": "string",

  

  

  

"tags": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"temperature": 0,

  

  

  

"title": "string"

  

  

}

  

],

  

"visibility": "string"

}

Samples

Suggest a description for a draft

POST

/v1/agent-drafts/{draft_id}/description:generate

Writes a one-sentence description of the draft's head version and RETURNS it without saving. Fill the field with it and let the author edit before they commit — a generator that wrote straight to the row would replace a sentence somebody had already written.

The source is the version's own name, instructions and tags; there is no way to pass text of your own.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"description": "string"

}

Samples

Publish a version as an agent

POST

/v1/agent-drafts/{draft_id}/publish

Creates an immutable agent from a version. A chat agent needs a prompt and a ready anchor word set. A tool agent needs a prompt and at least one enabled tool; anchor words play no part.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Any of

Format"uuid"

Format"uuid"

Any of

Valid values"personal""team_level""org_level""community""universal"

Responses

Successful Response

Content-Type

application/json

{

  

"agent_name": "string",

  

"agent_prompt": "string",

  

"anchor_word_candidates": [

  

  

"string"

  

],

  

"can_edit": false,

  

"can_write": false,

  

"chat_count": 0,

  

"chat_model": "string",

  

"color": "string",

  

"connector_providers": [

  

  

"string"

  

],

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"delist_listing_id": "string",

  

"description": "",

  

"enabled_tools": [

  

  

"string"

  

],

  

"has_chats": false,

  

"icon_name": "string",

  

"id": "string",

  

"is_system": false,

  

"listing_source_id": "string",

  

"max_tokens": 0,

  

"org_name": "string",

  

"pinned": false,

  

"ready": false,

  

"source_draft_id": "string",

  

"source_version_id": "string",

  

"tags": [

  

  

"string"

  

],

  

"team_ids": [

  

  

"string"

  

],

  

"temperature": 0,

  

"updated_at": "string",

  

"visibility": "string"

}

Samples

Commit a version

POST

/v1/agent-drafts/{draft_id}/versions

Creates a new version after the given parent. Any draft version may be used as the parent. If the parent already has descendants, returns 409 unless force=true (force deletes all descendants before creating the new version).

The tool tag is kept exactly as the draft was created: submitted tags can neither add nor remove it. A tool agent version may be saved with no tools.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Default""

Default""

Any of

Any of

Any of

Default""

Preview eval scores to persist with this version.

Any of

When true, deletes existing descendants of the parent before committing.

Defaultfalse

Any of

Any of

Default4096

Format"uuid"

Default0.7

Any of

Responses

Successful Response

Content-Type

application/json

{

  

"notice": "string",

  

"version": {

  

  

"agent_name": "string",

  

  

"agent_prompt": "string",

  

  

"anchor_word_count": 0,

  

  

"anchor_words": {

  

  

  

"additionalProperties": "string"

  

  

},

  

  

"anchor_words_ready": false,

  

  

"chat_model": "string",

  

  

"color": "string",

  

  

"created_at": "string",

  

  

"created_by": "string",

  

  

"description": "",

  

  

"draft_id": "string",

  

  

"embedding_status": "string",

  

  

"enabled_tools": [

  

  

  

"string"

  

  

],

  

  

"eval_scores": {

  

  

  

"additionalProperties": "string"

  

  

},

  

  

"eval_status": "string",

  

  

"golden_cases": [

  

  

  

{

  

  

  

  

"additionalProperties": "string"

  

  

  

}

  

  

],

  

  

"icon_name": "string",

  

  

"id": "string",

  

  

"max_tokens": 0,

  

  

"parent_version_id": "string",

  

  

"tags": [

  

  

  

"string"

  

  

],

  

  

"temperature": 0,

  

  

"title": "string"

  

}

}

Samples

Delete a version

DELETE

/v1/agent-drafts/{draft_id}/versions/{version_id}

Delete a single version and reparent its descendants onto the deleted version's
parent, keeping the chain connected.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

version_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Samples

Get one draft version

GET

/v1/agent-drafts/{draft_id}/versions/{version_id}

Read a single draft version. Used to poll eval_status after chat-agent-eval/start and to check anchor_words_ready before publishing.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

version_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"agent_name": "string",

  

"agent_prompt": "string",

  

"anchor_word_count": 0,

  

"anchor_words": {

  

  

"additionalProperties": "string"

  

},

  

"anchor_words_ready": false,

  

"chat_model": "string",

  

"color": "string",

  

"created_at": "string",

  

"created_by": "string",

  

"description": "",

  

"draft_id": "string",

  

"embedding_status": "string",

  

"enabled_tools": [

  

  

"string"

  

],

  

"eval_scores": {

  

  

"additionalProperties": "string"

  

},

  

"eval_status": "string",

  

"golden_cases": [

  

  

{

  

  

  

"additionalProperties": "string"

  

  

}

  

],

  

"icon_name": "string",

  

"id": "string",

  

"max_tokens": 0,

  

"parent_version_id": "string",

  

"tags": [

  

  

"string"

  

],

  

"temperature": 0,

  

"title": "string"

}

Samples

Rename a version

PATCH

/v1/agent-drafts/{draft_id}/versions/{version_id}

Set a custom title on a version. Titles otherwise default to sequential labels
(v1, v2, …); renaming does not affect that counter.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

version_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Max Length256

Min Length1

Responses

Successful Response

Content-Type

application/json

{

  

"agent_name": "string",

  

"agent_prompt": "string",

  

"anchor_word_count": 0,

  

"anchor_words": {

  

  

"additionalProperties": "string"

  

},

  

"anchor_words_ready": false,

  

"chat_model": "string",

  

"color": "string",

  

"created_at": "string",

  

"created_by": "string",

  

"description": "",

  

"draft_id": "string",

  

"embedding_status": "string",

  

"enabled_tools": [

  

  

"string"

  

],

  

"eval_scores": {

  

  

"additionalProperties": "string"

  

},

  

"eval_status": "string",

  

"golden_cases": [

  

  

{

  

  

  

"additionalProperties": "string"

  

  

}

  

],

  

"icon_name": "string",

  

"id": "string",

  

"max_tokens": 0,

  

"parent_version_id": "string",

  

"tags": [

  

  

"string"

  

],

  

"temperature": 0,

  

"title": "string"

}

Samples

Start an eval run (optionally execute golden cases)

POST

/v1/agent-drafts/{draft_id}/versions/{version_id}/chat-agent-eval/start

Starts prompt eval and/or golden-case eval against any draft version (head or historical). Returns immediately with eval_status "running"; results are persisted on that version when the run finishes. Poll GET .../versions/{version_id} until eval_status is "completed" or "failed".

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

version_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Any of

When run_golden is true, runs the version's persisted golden cases.

Defaultfalse

Responses

Successful Response

Content-Type

application/json

{

  

"agent_name": "string",

  

"agent_prompt": "string",

  

"anchor_word_count": 0,

  

"anchor_words": {

  

  

"additionalProperties": "string"

  

},

  

"anchor_words_ready": false,

  

"chat_model": "string",

  

"color": "string",

  

"created_at": "string",

  

"created_by": "string",

  

"description": "",

  

"draft_id": "string",

  

"embedding_status": "string",

  

"enabled_tools": [

  

  

"string"

  

],

  

"eval_scores": {

  

  

"additionalProperties": "string"

  

},

  

"eval_status": "string",

  

"golden_cases": [

  

  

{

  

  

  

"additionalProperties": "string"

  

  

}

  

],

  

"icon_name": "string",

  

"id": "string",

  

"max_tokens": 0,

  

"parent_version_id": "string",

  

"tags": [

  

  

"string"

  

],

  

"temperature": 0,

  

"title": "string"

}

Samples