> This page is for version v4 (default). > For other versions, use one of these documentation indexes: > - v4 (default): https://help.getzep.com/v4/llms.txt > - v3: https://help.getzep.com/v3/llms.txt > - v2: https://help.getzep.com/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.getzep.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server. # Compare Agent Skill Versions POST https://api.getzep.com/api/v4/agents/{agent_uuid}/skills/{skill_uuid}/versions/compare Content-Type: application/json Reference: https://help.getzep.com/sdk-reference/agent/skills/versions/compare ## Authentication - `Authorization` header (required) (prefixed with ` Api-Key `) — Type "Api-Key" followed by a space and the project API key. ## Request ### Path parameters - `agent_uuid` (string, required) — Agent UUID - `skill_uuid` (string, required) — Skill UUID ### Body (application/json) This endpoint expects a v4.CompareAgentSkillVersionsRequest. - `from_version` (integer, required) - `to_version` (integer, required) ## Response ### 200 OK - `changed_fields` (list of string, optional) - `from` (v4.AgentSkillVersion, optional) - `to` (v4.AgentSkillVersion, optional) ## Errors ### 400 Bad Request Error Bad Request - `error` (v4.ErrorBody, optional) ### 401 Unauthorized Error Unauthorized - `error` (v4.ErrorBody, optional) ### 403 Forbidden Error Forbidden - `error` (v4.ErrorBody, optional) ### 404 Not Found Error Not Found - `error` (v4.ErrorBody, optional) ### 503 Service Unavailable Error Service Unavailable - `error` (v4.ErrorBody, optional) ## Types ### v4.AgentSkillVersion - `contract` (v4.AgentSkillContract, optional) - `created_at` (string, optional) - `definition` (v4.SkillDefinition, optional) - `markdown` (string, optional) — Markdown is the agent view of the Skill unless the request selects `markdown_format=full`. - `self_contained` (boolean, optional) - `version` (integer, optional) ### v4.ErrorBody - `code` (string, optional) - `details` (map from string to any, optional) - `message` (string, optional) - `param` (string, optional) - `request_id` (string, optional) ### v4.AgentSkillContract - `aliases` (list of string, optional) - `applicability` (v4.AgentSkillContractApplicability, optional) - `citations` (list of string, optional) - `confidence` (double, optional) - `contraindications` (list of v4.AgentSkillContractText, optional) - `customer_sections` (list of v4.AgentSkillContractSection, optional) - `dependencies` (list of v4.AgentSkillContractDependency, optional) - `description` (string, optional) - `environments` (list of v4.AgentSkillContractResource, optional) - `evidence` (list of v4.AgentSkillContractEvidence, optional) - `failures` (list of v4.AgentSkillContractFailure, optional) - `invocation` (v4.AgentSkillContractInvocation, optional) - `kind` (enum, optional) - Allowed values: `principle`, `procedure`, `workflow`, `failure_mode`, `recovery`, `constraint` - `name` (string, optional) - `origin` (enum, optional) - Allowed values: `evidence_derived`, `customer_authored` - `outputs` (list of v4.AgentSkillContractText, optional) - `package_name` (string, optional) - `preconditions` (list of v4.AgentSkillContractText, optional) - `procedure` (list of v4.AgentSkillContractStep, optional) - `relations` (list of v4.AgentSkillContractRelation, optional) - `schema_version` (string, optional) - `success_criteria` (list of v4.AgentSkillContractText, optional) - `task_family` (string, optional) - `termination_conditions` (list of v4.AgentSkillContractText, optional) - `tools` (list of v4.AgentSkillContractResource, optional) ### v4.SkillDefinition - `agent_versions` (list of string, optional) - `aliases` (list of string, optional) - `description` (string, optional) - `do_not_use_when` (list of string, optional) - `done_when` (list of string, optional) - `environments` (list of v4.SkillResource, optional) - `failures` (list of v4.SkillFailure, optional) - `kind` (enum, optional) - Allowed values: `principle`, `procedure`, `workflow`, `failure_mode`, `recovery`, `constraint` - `name` (string, optional) - `outputs` (list of string, optional) - `package_name` (string, optional) - `preconditions` (list of string, optional) - `procedure` (list of v4.SkillProcedureStep, optional) - `related_skills` (list of v4.SkillRelation, optional) - `sections` (list of v4.SkillDefinitionSection, optional) - `stop_when` (list of string, optional) - `task_family` (string, optional) - `tools` (list of v4.SkillResource, optional) - `use_when` (list of string, optional) ### v4.AgentSkillContractApplicability - `agent_versions` (list of string, optional) - `citations` (list of string, optional) - `models` (list of v4.AgentSkillContractVersionConstraint, optional) ### v4.AgentSkillContractText - `citations` (list of string, optional) - `text` (string, optional) ### v4.AgentSkillContractSection - `heading` (string, optional) - `markdown` (string, optional) - `schema_version` (string, optional) - `section_id` (string, optional) ### v4.AgentSkillContractDependency - `package_name` (string, optional) - `version_constraint` (string, optional) ### v4.AgentSkillContractResource - `aliases` (list of string, optional) - `citations` (list of string, optional) - `name` (string, optional) - `version_constraint` (string, optional) ### v4.AgentSkillContractEvidence - `attempt_family_id` (string, optional) - `id` (string, optional) - `polarity` (enum, optional) - Allowed values: `supporting`, `contradicting`, `neutral` - `source_id` (string, optional) - `source_kind` (enum, optional) - Allowed values: `trajectory`, `event`, `summary` - `trajectory_id` (string, optional) ### v4.AgentSkillContractFailure - `condition` (v4.AgentSkillContractText, optional) - `recovery` (list of v4.AgentSkillContractText, optional) ### v4.AgentSkillContractInvocation - `conditions` (list of v4.AgentSkillContractText, optional) - `summary` (v4.AgentSkillContractText, optional) ### v4.AgentSkillContractStep - `decision` (v4.AgentSkillContractText, optional) - `expected_observations` (list of v4.AgentSkillContractText, optional) - `instruction` (v4.AgentSkillContractText, optional) ### v4.AgentSkillContractRelation - `citations` (list of string, optional) - `kind` (enum, optional) - Allowed values: `composes`, `requires`, `conflicts_with`, `supersedes`, `related` - `target_package_name` (string, optional) - `version_constraint` (string, optional) ### v4.SkillResource - `aliases` (list of string, optional) - `name` (string, optional) - `version` (string, optional) ### v4.SkillFailure - `recover` (list of string, optional) - `when` (string, optional) ### v4.SkillProcedureStep - `decision` (string, optional) - `expect` (list of string, optional) - `instruction` (string, optional) ### v4.SkillRelation - `relation` (string, optional) - `skill` (string, optional) - `version` (string, optional) ### v4.SkillDefinitionSection - `heading` (string, optional) - `id` (string, optional) - `markdown` (string, optional) ### v4.AgentSkillContractVersionConstraint - `name` (string, optional) - `version_constraint` (string, optional) ## Examples **Request** ```json { "from_version": 1, "to_version": 1 } ``` **Response** ```json { "changed_fields": [ "string" ], "from": { "contract": { "aliases": [ "string" ], "applicability": { "agent_versions": [ "string" ], "citations": [ "string" ], "models": [ { "name": "string", "version_constraint": "string" } ] }, "citations": [ "string" ], "confidence": 1.1, "contraindications": [ { "citations": [ "string" ], "text": "string" } ], "customer_sections": [ { "heading": "string", "markdown": "string", "schema_version": "string", "section_id": "string" } ], "dependencies": [ { "package_name": "string", "version_constraint": "string" } ], "description": "string", "environments": [ { "aliases": [ "string" ], "citations": [ "string" ], "name": "string", "version_constraint": "string" } ], "evidence": [ { "attempt_family_id": "string", "id": "string", "polarity": "supporting", "source_id": "string", "source_kind": "trajectory", "trajectory_id": "string" } ], "failures": [ { "condition": { "citations": [ "string" ], "text": "string" }, "recovery": [ { "citations": [ "string" ], "text": "string" } ] } ], "invocation": { "conditions": [ { "citations": [ "string" ], "text": "string" } ], "summary": { "citations": [ "string" ], "text": "string" } }, "kind": "principle", "name": "string", "origin": "evidence_derived", "outputs": [ { "citations": [ "string" ], "text": "string" } ], "package_name": "string", "preconditions": [ { "citations": [ "string" ], "text": "string" } ], "procedure": [ { "decision": { "citations": [ "string" ], "text": "string" }, "expected_observations": [ { "citations": [ "string" ], "text": "string" } ], "instruction": { "citations": [ "string" ], "text": "string" } } ], "relations": [ { "citations": [ "string" ], "kind": "composes", "target_package_name": "string", "version_constraint": "string" } ], "schema_version": "string", "success_criteria": [ { "citations": [ "string" ], "text": "string" } ], "task_family": "string", "termination_conditions": [ { "citations": [ "string" ], "text": "string" } ], "tools": [ { "aliases": [ "string" ], "citations": [ "string" ], "name": "string", "version_constraint": "string" } ] }, "created_at": "string", "definition": { "agent_versions": [ "string" ], "aliases": [ "string" ], "description": "string", "do_not_use_when": [ "string" ], "done_when": [ "string" ], "environments": [ { "aliases": [ "string" ], "name": "string", "version": "string" } ], "failures": [ { "recover": [ "string" ], "when": "string" } ], "kind": "principle", "name": "string", "outputs": [ "string" ], "package_name": "string", "preconditions": [ "string" ], "procedure": [ { "decision": "string", "expect": [ "string" ], "instruction": "string" } ], "related_skills": [ { "relation": "string", "skill": "string", "version": "string" } ], "sections": [ { "heading": "string", "id": "string", "markdown": "string" } ], "stop_when": [ "string" ], "task_family": "string", "tools": [ { "aliases": [ "string" ], "name": "string", "version": "string" } ], "use_when": [ "string" ] }, "markdown": "string", "self_contained": true, "version": 1 }, "to": { "contract": { "aliases": [ "string" ], "applicability": { "agent_versions": [ "string" ], "citations": [ "string" ], "models": [ { "name": "string", "version_constraint": "string" } ] }, "citations": [ "string" ], "confidence": 1.1, "contraindications": [ { "citations": [ "string" ], "text": "string" } ], "customer_sections": [ { "heading": "string", "markdown": "string", "schema_version": "string", "section_id": "string" } ], "dependencies": [ { "package_name": "string", "version_constraint": "string" } ], "description": "string", "environments": [ { "aliases": [ "string" ], "citations": [ "string" ], "name": "string", "version_constraint": "string" } ], "evidence": [ { "attempt_family_id": "string", "id": "string", "polarity": "supporting", "source_id": "string", "source_kind": "trajectory", "trajectory_id": "string" } ], "failures": [ { "condition": { "citations": [ "string" ], "text": "string" }, "recovery": [ { "citations": [ "string" ], "text": "string" } ] } ], "invocation": { "conditions": [ { "citations": [ "string" ], "text": "string" } ], "summary": { "citations": [ "string" ], "text": "string" } }, "kind": "principle", "name": "string", "origin": "evidence_derived", "outputs": [ { "citations": [ "string" ], "text": "string" } ], "package_name": "string", "preconditions": [ { "citations": [ "string" ], "text": "string" } ], "procedure": [ { "decision": { "citations": [ "string" ], "text": "string" }, "expected_observations": [ { "citations": [ "string" ], "text": "string" } ], "instruction": { "citations": [ "string" ], "text": "string" } } ], "relations": [ { "citations": [ "string" ], "kind": "composes", "target_package_name": "string", "version_constraint": "string" } ], "schema_version": "string", "success_criteria": [ { "citations": [ "string" ], "text": "string" } ], "task_family": "string", "termination_conditions": [ { "citations": [ "string" ], "text": "string" } ], "tools": [ { "aliases": [ "string" ], "citations": [ "string" ], "name": "string", "version_constraint": "string" } ] }, "created_at": "string", "definition": { "agent_versions": [ "string" ], "aliases": [ "string" ], "description": "string", "do_not_use_when": [ "string" ], "done_when": [ "string" ], "environments": [ { "aliases": [ "string" ], "name": "string", "version": "string" } ], "failures": [ { "recover": [ "string" ], "when": "string" } ], "kind": "principle", "name": "string", "outputs": [ "string" ], "package_name": "string", "preconditions": [ "string" ], "procedure": [ { "decision": "string", "expect": [ "string" ], "instruction": "string" } ], "related_skills": [ { "relation": "string", "skill": "string", "version": "string" } ], "sections": [ { "heading": "string", "id": "string", "markdown": "string" } ], "stop_when": [ "string" ], "task_family": "string", "tools": [ { "aliases": [ "string" ], "name": "string", "version": "string" } ], "use_when": [ "string" ] }, "markdown": "string", "self_contained": true, "version": 1 } } ```