Reference

Compare versions

Structured diff between two versions, or a version and the current configuration ("current").

REST	`GET /api/v1/agents/{agent_id}/diff`
MCP tool	`diff_versions`
Classification	Read (changes nothing)
Scope	`agents:read`
Minimum role on the agent	editor
Confirmation	Not needed
Retry safety	Safe to retry with the same input
Success status	200

What it does

Structured diff between two versions, or a version and the current configuration ("current").

Side effects

None. It only reads.

Inputs

Name	Type	Required	In	Description
`agent_id`	string	yes	path	The agent id (agt_...), from list_agents.
`from`	integer or "current"	yes	query
`to`	integer or "current"	no	query	Default "current".

Example

REST

curl "https://covo.lanaai.io/api/v1/agents/agt_4edc89bb2964/diff?from=1&to=current" \
  -H "Authorization: Bearer $COVO_TOKEN"

MCP (POST /mcp)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "diff_versions",
    "arguments": {
      "agent_id": "agt_4edc89bb2964",
      "from": 1,
      "to": "current"
    }
  }
}

Response

Returns an object with from, to and changes. This is a real response, shortened to two items per list.

200 response

{
  "from": 1,
  "to": "current",
  "changes": [
    {
      "path": "personality.tone",
      "operation": "replace",
      "before": "warm",
      "after": "Warm, direct and practical."
    },
    {
      "path": "personality.greeting",
      "operation": "replace",
      "before": "I'm Avery Quinn's Concierge. I can help you learn about Avery Quinn's work, what's on offer, or anything else you're curious about.",
      "after": "Hi, I am Avery’s Concierge. Ask me about spring projects."
    }
  ]
}

Over MCP the same object comes back as the tool result, in structuredContent and as JSON text.

Errors

Status	Code	Meaning
401	`unauthorized`	No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect.
403	`account_suspended`	The account that owns the token is paused.
403	`insufficient_scope`	The token lacks `agents:read`.
404	`agent_not_found`	Unknown agent, or not reachable with this token.
400	`bad_request`	An input is invalid; `field` names it.
429	`rate_limited`	Wait `Retry-After` seconds.