Ragavan

Version

Public API version information.

GET /api/v0/version

Public

Get API version and current version string.

Example

curl \
  -s https://ragavan.com/api/v0/version

Response

HTTP 200

{
  "version": "0.x.y",
  "api": "v0"
}

Response parameters

Schema: Version

Name	Type	Description
version	string	Semantic version of server
api	string	API namespace (e.g., 'v0')

Authentication

GET /api/v0/auth

Bearer

Get authenticated profile (validate token).

Example

curl \
  -s https://ragavan.com/api/v0/auth \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

{
  "user": "admin",
  "type": "Admin"
}

Response parameters

Schema: AuthProfile

Name	Type	Description
user	string	Principal name
type	string	'Admin' or 'User'

Agents

Agent lifecycle and management endpoints (protected).

GET /api/v0/agents

Bearer

List agents.

Query parameters

Name	Type	Req	Description
state	string	no	Filter by state (e.g., init\|idle\|busy\|slept)

Example

curl \
  -s https://ragavan.com/api/v0/agents \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

[{"name":"demo","created_by":"admin","state":"idle","description":null,"parent_agent_name":null,"created_at":"2025-01-01T12:00:00Z","last_activity_at":"2025-01-01T12:10:00Z","metadata":{},"tags":[],"is_published":false,"published_at":null,"published_by":null,"publish_permissions":{"code":true,"secrets":true,"content":true},"idle_timeout_seconds":300,"busy_timeout_seconds":900,"idle_from":"2025-01-01T12:10:00Z","busy_from":null}]

Response parameters

Schema: Agent[]

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

POST /api/v0/agents

Bearer

Create agent.

Body fields

Name	Type	Req	Description
name	string	yes	Agent name; must match ^[A-Za-z][A-Za-z0-9-]{0,61}[A-Za-z0-9]$
description	string\|null	no	Optional human-readable description
metadata	object	no	Arbitrary JSON metadata (default: {})
tags	string[]	no	Array of tags; each tag must be alphanumeric (A-Za-z0-9), no spaces/symbols (default: [])
secrets	object<string,string>	no	Key/value secrets map (default: empty)
instructions	string\|null	no	Optional instructions
setup	string\|null	no	Optional setup script or commands
prompt	string\|null	no	Optional initial prompt
idle_timeout_seconds	int\|null	no	Idle timeout seconds (default 300)
busy_timeout_seconds	int\|null	no	Busy timeout seconds (default 900)

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","description":"Demo agent"}'

Response

HTTP 200

{"name":"demo","created_by":"admin","state":"init","description":"Demo agent","parent_agent_name":null,"created_at":"2025-01-01T12:00:00Z","last_activity_at":null,"metadata":{},"tags":[],"is_published":false,"published_at":null,"published_by":null,"publish_permissions":{"code":true,"secrets":true,"content":true},"idle_timeout_seconds":300,"busy_timeout_seconds":900,"idle_from":null,"busy_from":null}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

GET /api/v0/agents/{name}

Bearer

Get agent by name.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s https://ragavan.com/api/v0/agents/<name> \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

{"name":"demo","created_by":"admin","state":"idle","description":"Demo agent","parent_agent_name":null,"created_at":"2025-01-01T12:00:00Z","last_activity_at":"2025-01-01T12:10:00Z","metadata":{},"tags":[],"is_published":false,"published_at":null,"published_by":null,"publish_permissions":{"code":true,"secrets":true,"content":true},"idle_timeout_seconds":300,"busy_timeout_seconds":900,"idle_from":"2025-01-01T12:10:00Z","busy_from":null}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

PUT /api/v0/agents/{name}

Bearer

Update agent by name.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Body fields

Name	Type	Req	Description
metadata	object\|null	no	Replace metadata (omit to keep)
description	string\|null	no	Update description
tags	string[]\|null	no	Replace tags array; each tag must be alphanumeric (A-Za-z0-9), no spaces/symbols
idle_timeout_seconds	int\|null	no	Update idle timeout seconds
busy_timeout_seconds	int\|null	no	Update busy timeout seconds

Example

curl \
  -s \
  -X PUT \
  https://ragavan.com/api/v0/agents/<name> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated"}'

Response

HTTP 200

{"name":"demo","created_by":"admin","state":"idle","description":"Updated","parent_agent_name":null,"created_at":"2025-01-01T12:00:00Z","last_activity_at":"2025-01-01T12:20:00Z","metadata":{},"tags":[],"is_published":false,"published_at":null,"published_by":null,"publish_permissions":{"code":true,"secrets":true,"content":true},"idle_timeout_seconds":300,"busy_timeout_seconds":900,"idle_from":"2025-01-01T12:20:00Z","busy_from":null}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

PUT /api/v0/agents/{name}/state

Bearer

Update agent state (generic).

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Body fields

Name	Type	Req	Description
state	string	yes	New state (e.g., init\|idle\|busy\|slept)

Example

curl \
  -s \
  -X PUT \
  https://ragavan.com/api/v0/agents/<name>/state \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"state":"idle"}'

Response

HTTP 200

{"success":true,"state":"idle"}

Response parameters

Schema: StateAck

Name	Type	Description
success	boolean	true on success
state	string	New state value

POST /api/v0/agents/{name}/busy

Bearer

Set agent busy.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/busy \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

{"success":true,"state":"busy","timeout_status":"paused"}

Response parameters

Schema: BusyIdleAck

Name	Type	Description
success	boolean	true on success
state	string	'busy' or 'idle'
timeout_status	string	'paused' (busy) or 'active' (idle)

POST /api/v0/agents/{name}/idle

Bearer

Set agent idle.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/idle \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

{"success":true,"state":"idle","timeout_status":"active"}

Response parameters

Schema: BusyIdleAck

Name	Type	Description
success	boolean	true on success
state	string	'busy' or 'idle'
timeout_status	string	'paused' (busy) or 'active' (idle)

POST /api/v0/agents/{name}/sleep

Bearer

Put agent to sleep.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/sleep \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

{"name":"demo","created_by":"admin","state":"slept",...}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

POST /api/v0/agents/{name}/wake

Bearer

Wake agent.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Body fields

Name	Type	Req	Description
prompt	string\|null	no	Optional prompt to send on wake

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/wake \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"get ready"}'

Response

HTTP 200

{"name":"demo","created_by":"admin","state":"init",...}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

POST /api/v0/agents/{name}/remix

Bearer

Remix agent (create a new agent from parent).

Path parameters

Name	Type	Req	Description
name	string	yes	Parent agent name

Body fields

Name	Type	Req	Description
name	string	yes	New agent name; must match ^[A-Za-z][A-Za-z0-9-]{0,61}[A-Za-z0-9]$
metadata	object\|null	no	Optional metadata override
code	boolean	no	Copy code (default true)
secrets	boolean	no	Copy secrets (default true)
content	boolean	no	Copy content (always true in v0.4.0+)
prompt	string\|null	no	Optional initial prompt

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/remix \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo-copy","code":true,"secrets":false,"prompt":"clone and adjust"}'

Response

HTTP 200

{"name":"demo-copy","created_by":"admin","state":"init",...}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

POST /api/v0/agents/{name}/publish

Bearer

Publish agent.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Body fields

Name	Type	Req	Description
code	boolean	no	Allow code remix (default true)
secrets	boolean	no	Allow secrets remix (default true)
content	boolean	no	Publish content (default true)

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/publish \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"code":true,"secrets":false,"content":true}'

Response

HTTP 200

{"name":"demo","is_published":true,"published_at":"2025-01-01T12:30:00Z",...}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

POST /api/v0/agents/{name}/unpublish

Bearer

Unpublish agent.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/unpublish \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

{"name":"demo","is_published":false,"published_at":null,...}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

DELETE /api/v0/agents/{name}

Bearer

Delete agent.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s \
  -X DELETE \
  https://ragavan.com/api/v0/agents/<name> \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

Response parameters

No JSON body.

Agent Responses

Composite input→output exchanges with live items (protected).

GET /api/v0/agents/{name}/responses

Bearer

List responses for agent.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Query parameters

Name	Type	Req	Description
limit	int	no	Max responses (0..1000, default 100)
offset	int	no	Offset for pagination (default 0)

Example

curl \
  -s https://ragavan.com/api/v0/agents/<name>/responses?limit=20 \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

[{"id":"uuid","agent_name":"demo","status":"completed","input":{"text":"hi"},"output":{"text":"hello","items":[]},"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:10Z"}]

Response parameters

Schema: ResponseObject[]

Name	Type	Description
id	string	Response ID (UUID)
agent_name	string	Agent name
status	string	'pending'\|'processing'\|'completed'\|'failed'
input	object	User input JSON (e.g., { text: string })
output	object	Agent output JSON (see items structure)
created_at	string (RFC3339)	Creation timestamp
updated_at	string (RFC3339)	Last update timestamp

POST /api/v0/agents/{name}/responses

Bearer

Create a response (user input). Supports blocking when background=false.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Body fields

Name	Type	Req	Description
input	object	yes	User input; shape: { text: string }
background	boolean	no	Default true. If false, request blocks up to 15 minutes until the response reaches a terminal status (completed\|failed). Returns 504 on timeout. If true or omitted, returns immediately (typically status=pending).

Example

curl \
  -s \
  -X POST \
  https://ragavan.com/api/v0/agents/<name>/responses \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"input":{"text":"hello"},"background":false}'

Response

HTTP 200

{"id":"uuid","status":"completed",...}

HTTP 504

{"message":"Timed out waiting for response to complete"}

Response parameters

Schema: ResponseObject

Name	Type	Description
id	string	Response ID (UUID)
agent_name	string	Agent name
status	string	'pending'\|'processing'\|'completed'\|'failed'
input	object	User input JSON (e.g., { text: string })
output	object	Agent output JSON (see items structure)
created_at	string (RFC3339)	Creation timestamp
updated_at	string (RFC3339)	Last update timestamp

PUT /api/v0/agents/{name}/responses/{id}

Bearer

Update a response (agent-only typical). Used to append output.items and mark status.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name
id	string	yes	Response id

Body fields

Name	Type	Req	Description
status	'pending'\|'processing'\|'completed'\|'failed'	no	Status update
input	object	no	Optional input update; replaces existing input JSON
output	object	no	Output update; shape: { text?: string, items?: [] }

Example

curl \
  -s \
  -X PUT \
  https://ragavan.com/api/v0/agents/<name>/responses/<id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed","output":{"text":"done","items":[{"type":"final","text":"done"}]}}'

Response

HTTP 200

{"id":"uuid","status":"completed",...}

Response parameters

Schema: ResponseObject

Name	Type	Description
id	string	Response ID (UUID)
agent_name	string	Agent name
status	string	'pending'\|'processing'\|'completed'\|'failed'
input	object	User input JSON (e.g., { text: string })
output	object	Agent output JSON (see items structure)
created_at	string (RFC3339)	Creation timestamp
updated_at	string (RFC3339)	Last update timestamp

GET /api/v0/agents/{name}/responses/count

Bearer

Get response count for agent.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s https://ragavan.com/api/v0/agents/<name>/responses/count \
  -H "Authorization: Bearer <token>"

Response

HTTP 200

{"count":123,"agent_name":"demo"}

Response parameters

Schema: Count

Name	Type	Description
count	int	Count value
agent_name	string	Agent identifier

Published Agents (Public)

Publicly visible agents and details.

GET /api/v0/published/agents

Public

List all published agents.

Example

curl \
  -s https://ragavan.com/api/v0/published/agents

Response

HTTP 200

[
  {
    "name": "demo",
    "created_by": "admin",
    "state": "idle",
    "description": "Demo agent",
    "parent_agent_name": null,
    "created_at": "2025-01-01T12:00:00Z",
    "last_activity_at": "2025-01-01T12:00:00Z",
    "metadata": {},
    "tags": ["example"],
    "is_published": true,
    "published_at": "2025-01-01T12:30:00Z",
    "published_by": "admin",
    "publish_permissions": {"code": true, "secrets": false, "content": true},
    "idle_timeout_seconds": 300,
    "busy_timeout_seconds": 900,
    "idle_from": "2025-01-01T12:10:00Z",
    "busy_from": null
  }
]

Response parameters

Schema: Agent[]

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

GET /api/v0/published/agents/{name}

Public

Get details of a published agent by name.

Path parameters

Name	Type	Req	Description
name	string	yes	Agent name

Example

curl \
  -s https://ragavan.com/api/v0/published/agents/<name>

Response

HTTP 200

{
  "name": "demo",
  "created_by": "admin",
  "state": "idle",
  "description": "Demo agent",
  "parent_agent_name": null,
  "created_at": "2025-01-01T12:00:00Z",
  "last_activity_at": "2025-01-01T12:00:00Z",
  "metadata": {},
  "tags": ["example"],
  "is_published": true,
  "published_at": "2025-01-01T12:30:00Z",
  "published_by": "admin",
  "publish_permissions": {"code": true, "secrets": false, "content": true},
  "idle_timeout_seconds": 300,
  "busy_timeout_seconds": 900,
  "idle_from": "2025-01-01T12:10:00Z",
  "busy_from": null
}

Response parameters

Schema: Agent

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	{ code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

Error Format

On error, endpoints return an HTTP status and a JSON body:

{
  "message": "Error description"
}

Response Object

Standard object returned by /api/v0/agents/{name}/responses endpoints.

Name	Type	Description
id	string	Response ID (UUID)
agent_name	string	Agent name
status	string	One of: pending, processing, completed, failed
input	object	User input JSON (typically { text: string })
output	object	Agent output JSON with fields below
created_at	string (RFC3339)	Creation timestamp (UTC)
updated_at	string (RFC3339)	Last update timestamp (UTC)

output fields

Name	Type	Description
text	string	Final assistant message (may be empty while processing)
items	array	Ordered list of structured items (see “Items Structure”)

GET list is ordered by created_at ascending.
Update semantics: output.text replaces; output.items appends; other output keys overwrite.
Typical input is { text: string }, but arbitrary JSON is allowed.

Items Structure (output.items)

The output.items array captures step-by-step progress, tool usage, and final output. Items are appended in order.

The tool_result.output value may be plain text or structured JSON. The UI renders JSON objects/arrays directly and falls back to strings for text outputs.

Item types

type	Shape	Purpose
commentary	{ type, channel: 'analysis', text }	Internal thinking/analysis. Hidden in UI unless details are shown.
tool_call	{ type, tool, args }	Declares a tool invocation with arguments.
tool_result	{ type, tool, output }	Result of the preceding matching tool_call.
final	{ type, channel: 'final', text }	Final assistant answer (mirrors output.text).

Examples

{
  "type": "commentary",
  "channel": "analysis",
  "text": "Thinking about the approach…"
}

{
  "type": "tool_call",
  "tool": "bash",
  "args": {
    "command": "ls -la",
    "cwd": "/agent/code"
  }
}

{
  "type": "tool_result",
  "tool": "bash",
  "output": "[exit_code:0]\nREADME.md\nsrc/"
}

{
  "type": "final",
  "channel": "final",
  "text": "All set! Here are the results…"
}

Notes: Tool outputs may be truncated for size; the UI pairs each tool_call with the next tool_result having the same tool.

Common Response Schemas

Version

Name	Type	Description
version	string	Semantic version of server
api	string	API namespace (e.g., v0)

Auth Profile

Name	Type	Description
user	string	Principal name
type	string	Admin or User

Token Response

Name	Type	Description
token	string	JWT token
token_type	string	Always Bearer
expires_at	string (RFC3339)	Expiry timestamp
user	string	Principal name associated with token
role	string	admin or user

Operator Object

Name	Type	Description
user	string	Operator username
description	string\|null	Optional description
active	boolean	Account active flag
created_at	string (RFC3339)	Creation timestamp
updated_at	string (RFC3339)	Last update timestamp
last_login_at	string\|null (RFC3339)	Last login timestamp, if any

Agent Object

Name	Type	Description
name	string	Agent name (primary key)
created_by	string	Owner username
state	string	init\|idle\|busy\|slept
description	string\|null	Optional description
parent_agent_name	string\|null	Parent agent name if remixed
created_at	string (RFC3339)	Creation timestamp
last_activity_at	string\|null (RFC3339)	Last activity timestamp
metadata	object	Arbitrary JSON metadata
tags	string[]	Array of alphanumeric tags
is_published	boolean	Published state
published_at	string\|null (RFC3339)	When published
published_by	string\|null	Who published
publish_permissions	object	Flags object: { code: boolean, secrets: boolean, content: boolean }
idle_timeout_seconds	int	Idle timeout
busy_timeout_seconds	int	Busy timeout
idle_from	string\|null (RFC3339)	When idle started
busy_from	string\|null (RFC3339)	When busy started

Count Object

Name	Type	Description
count	int	Count value
agent_name	string	Agent identifier the count pertains to

Agent Busy/Idle Response

Name	Type	Description
success	boolean	Always true on success
state	string	busy or idle
timeout_status	string	paused (busy) or active (idle)

Agent State Update Response

Name	Type	Description
success	boolean	Always true on success
state	string	New state string

Sections

Version Authentication Agents Agent Responses Published Agents (Public)