> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt > Use this file to discover all available pages before exploring further. # Compare two versions > What changed between any two versions. ```http theme={"dark"} GET /v1/agents/{agent_id}/compare?left=4&right=7 ``` Any pair — not only draft against live. Each difference names the field **as this API names it**, so you can act on it directly: ```json theme={"dark"} { "differences": [ { "field": "voice.speed", "change": "changed", "before": 1.0, "after": 1.3 }, { "field": "builtin_tools.transfer_call.numbers[0].number", "change": "changed", "before": "+919876543210", "after": "+919876500000" } ] } ``` Compares configuration only. Labels, timestamps and version numbers are not differences in how the agent behaves, and neither are the agent's tools — those are a dashboard surface, so a difference never names a field you cannot read or write here. ## OpenAPI ````yaml developers/openapi.json GET /v1/agents/{agent_id}/compare openapi: 3.1.0 info: title: Vocily API description: >- Public REST API for Vocily. Build and configure an agent, publish a version and put it live, place outbound calls, and read back calls, chats and what the agent remembered. Authenticate with a workspace API key as a Bearer token. Some things stay in the dashboard, by design: creating an API key, buying or connecting a phone number, setting an agent's webhook URL, connecting WhatsApp and its templates, building HTTP tools, and running batch campaigns. version: v1 servers: - url: https://api.vocily.ai description: Production security: [] paths: /v1/agents/{agent_id}/compare: get: tags: - agent-versions summary: Compare Versions description: >- Compare any two versions — any pair, not only a draft against the live version. Compares configuration only. Labels, timestamps and version numbers are left out of the diff: they say nothing about how the agent behaves. operationId: compare_versions_v1_agents__agent_id__compare_get parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id description: The agent's id, as `GET /v1/agents` returns it. - name: left in: query required: true schema: type: string description: version number, e.g. `3` title: Left description: version number, e.g. `3` - name: right in: query required: true schema: type: string description: version number, e.g. `4` title: Right description: version number, e.g. `4` responses: '200': description: >- What differs between the two versions, named in this API's own fields. content: application/json: schema: $ref: '#/components/schemas/PublicVersionCompare' example: left: version: 0 version_id: 00000006-0000-4000-8000-000000000006 is_published: true is_live: true label: Renamed notes: null base_version: null document_revision: 2 blocked_reasons: [] inbound_phone: null inbound_whatsapp: null created_at: '2026-09-16T19:38:03.767024Z' published_at: '2026-09-16T19:38:03.999783Z' right: version: 1 version_id: 0000000a-0000-4000-8000-00000000000a is_published: false is_live: false label: null notes: null base_version: 0 document_revision: 2 blocked_reasons: [] inbound_phone: null inbound_whatsapp: null created_at: '2026-09-16T19:38:04.059129Z' published_at: null differences: - field: call.max_duration_minutes change: changed before: 5 after: 9 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: detail: Invalid API key code: UNAUTHORIZED '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded — honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: rate_limited security: - bearerAuth: [] components: schemas: PublicVersionCompare: additionalProperties: false properties: left: $ref: '#/components/schemas/PublicVersionSummary' description: The first version of the pair. right: $ref: '#/components/schemas/PublicVersionSummary' description: The second version of the pair. differences: description: >- Every configuration field that differs, in PUBLIC field paths — the same paths you send on a PATCH. Metadata (labels, timestamps, version numbers) is excluded: it always differs and says nothing about behaviour. items: $ref: '#/components/schemas/VersionDiff' title: Differences type: array required: - left - right title: PublicVersionCompare type: object ApiError: type: object description: >- Error envelope. `code` is derived from the HTTP status, so branch on it for the CLASS of failure; the specific reason is `detail.code`. Every public refusal carries both. properties: detail: type: object description: >- The reason. `code` is the domain reason (e.g. `call_not_found`) and `message` is a sentence safe to log. On a `422` it also carries `errors[]`, one entry per rejected field — see `HTTPValidationError`. properties: code: type: string example: call_not_found message: type: string example: Call not found required: - code - message code: type: string description: Derived from the HTTP status, not the domain reason. example: NOT_FOUND HTTPValidationError: type: object title: HTTPValidationError description: >- A request the API could not read: a field of the wrong type, out of range, missing, or one we do not accept. Same envelope as every other error. properties: detail: type: object description: >- What was wrong, as `code`, a one-line `message`, and every offending field in `errors`. required: - code - message - errors properties: code: type: string enum: - validation_error message: type: string description: >- The first problem in one line, with a count of the rest — e.g. `model.temperature: Input should be less than or equal to 2 (and 1 more)`. errors: type: array items: $ref: '#/components/schemas/ValidationError' description: >- One entry per offending field. **Every problem is reported at once**, not just the first, so a malformed body needs one round trip to fix rather than one per field. code: type: string enum: - VALIDATION_ERROR description: Derived from the HTTP status, as on every error. PublicVersionSummary: additionalProperties: false description: >- One version in an agent's history. Versions are identified by NUMBER: it is what every version read returns and what `?version=` and `/versions/{n}` take. properties: version: description: This version's number — what you pass in `/versions/{n}`. title: Version type: integer version_id: description: >- This version's uuid. Published because `POST /v1/calls` pins a call with `agent_version_id`, which takes a uuid rather than a number. title: Version Id type: string is_published: description: >- True once frozen. Configuration can never be edited again; `label` and `notes` still can. title: Is Published type: boolean is_live: description: True if this is the version answering calls right now. title: Is Live type: boolean label: anyOf: - type: string - type: 'null' default: null description: Short name for this version. title: Label notes: anyOf: - type: string - type: 'null' default: null description: Longer free text about this version. title: Notes base_version: anyOf: - type: integer - type: 'null' default: null description: >- Which version this one was branched from, by NUMBER — `null` for the agent's first. title: Base Version document_revision: description: >- This version's edit counter. Send it as `If-Match` to make a write conditional. title: Document Revision type: integer blocked_reasons: description: >- Why this version cannot be made live, if it cannot — e.g. it pins a retired model. Check it before offering a deploy button, so the button never fails on click. items: type: string title: Blocked Reasons type: array inbound_phone: anyOf: - type: string - type: 'null' default: null description: >- The phone number this version will answer on once it is made live. Inert until then. title: Inbound Phone inbound_whatsapp: anyOf: - type: string - type: 'null' default: null description: >- The WhatsApp number this version will answer on once it is made live. Inert until then. title: Inbound Whatsapp created_at: description: When this version was created (UTC, ISO 8601). format: date-time title: Created At type: string published_at: anyOf: - type: string format: date-time - type: 'null' default: null description: When it was frozen. `null` while it is still a draft. title: Published At required: - version - version_id - is_published - is_live - document_revision - created_at title: PublicVersionSummary type: object VersionDiff: additionalProperties: false description: >- One difference between two versions, in the PUBLIC field vocabulary. `field` is the path as this API names it (`voice.voice_id`), not the stored path (`core.voice_config.tts.voice`) — a diff a customer cannot map back onto the fields they set is a diff they cannot act on. properties: field: description: >- The field that differs, as a PUBLIC path — the same path you would send on a PATCH. title: Field type: string change: description: Whether it was added, removed, or changed between the two versions. enum: - added - removed - changed title: Change type: string before: default: null description: Its value on the left version. title: Before after: default: null description: Its value on the right version. title: After required: - field - change title: VersionDiff type: object ValidationError: type: object title: ValidationError required: - field - message - type properties: field: type: string description: >- The offending field as a path from the root of your request — `voice.speed`, `variables[0].key`, or `query.limit` for a query parameter. **This is the field to read.** message: type: string description: What is wrong with it, in plain language. type: type: string description: >- A stable machine code for the kind of failure, e.g. `extra_forbidden` for a field we do not accept, `missing` for a required one, or `less_than_equal` for a number out of range. Switch on this rather than on `message`, which may be reworded. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.' ````