# 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:

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

MCP (POST /mcp):

```json
{
  "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:

```json
{
  "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. |