{
  "openapi": "3.1.0",
  "info": {
    "title": "PatchPath AI Code Edit API",
    "version": "1.0.2",
    "description": "Snapshot-pinned source context and structured code edit protocol for AI coding agents."
  },
  "servers": [{ "url": "https://patchpath.vercel.app/api/v1", "description": "Production" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "PatchPath API key (ctx_edit_..., ctx_read_..., etc.)" }
    },
    "parameters": {
      "ProjectKey": { "name": "projectKey", "in": "path", "required": true, "schema": { "type": "string" } },
      "ContextId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
      "EditId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
      "ValidationId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
    },
    "schemas": {
      "ApiMeta": {
        "type": "object",
        "properties": {
          "requestId": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date-time" }
        },
        "required": ["requestId", "generatedAt"]
      },
      "ErrorBody": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error code",
                "examples": [
                  "READ_BEFORE_EDIT_REQUIRED",
                  "SOURCE_HASH_MISMATCH",
                  "WORKSPACE_REVISION_MISMATCH",
                  "AMBIGUOUS_ANCHOR",
                  "FORBIDDEN_PATH_REQUESTED",
                  "VALIDATION_REQUIRED",
                  "API_KEY_SCOPE_DENIED"
                ]
              },
              "message": { "type": "string" },
              "recoverable": { "type": "boolean" },
              "requestId": { "type": "string" }
            },
            "required": ["code", "message", "recoverable", "requestId"]
          }
        },
        "required": ["error"]
      },
      "ObjectHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
      "EditTarget": {
        "type": "object",
        "required": ["path"],
        "properties": {
          "path": { "type": "string", "description": "Repository-relative normalized path" },
          "baseObjectHash": { "$ref": "#/components/schemas/ObjectHash", "description": "Required for existing files; must match the latest read response" }
        }
      },
      "EditPayloadExact": {
        "type": "object",
        "required": ["oldText", "newText"],
        "properties": {
          "oldText": { "type": "string" },
          "newText": { "type": "string" },
          "expectedOccurrences": { "type": "integer", "minimum": 1, "default": 1 }
        }
      },
      "EditPayloadAnchored": {
        "type": "object",
        "required": ["oldText", "newText", "anchorBefore", "anchorAfter"],
        "properties": {
          "oldText": { "type": "string" },
          "newText": { "type": "string" },
          "anchorBefore": { "type": "string" },
          "anchorAfter": { "type": "string" },
          "expectedOccurrences": { "type": "integer", "minimum": 1, "default": 1 }
        }
      },
      "EditPayloadInsert": {
        "type": "object",
        "required": ["oldText", "newText"],
        "properties": {
          "oldText": { "type": "string" },
          "newText": { "type": "string" },
          "expectedOccurrences": { "type": "integer", "minimum": 1, "default": 1 }
        }
      },
      "EditPayloadFile": {
        "type": "object",
        "required": ["content"],
        "properties": { "content": { "type": "string" } }
      },
      "ReplaceExactOperation": {
        "type": "object",
        "required": ["operationId", "type", "target", "edit"],
        "properties": {
          "operationId": { "type": "string" },
          "type": { "const": "replace_exact" },
          "target": { "$ref": "#/components/schemas/EditTarget" },
          "reason": { "type": "string" },
          "edit": { "$ref": "#/components/schemas/EditPayloadExact" }
        }
      },
      "ReplaceAnchoredOperation": {
        "type": "object",
        "required": ["operationId", "type", "target", "edit"],
        "properties": {
          "operationId": { "type": "string" },
          "type": { "const": "replace_anchored" },
          "target": { "$ref": "#/components/schemas/EditTarget" },
          "reason": { "type": "string" },
          "edit": { "$ref": "#/components/schemas/EditPayloadAnchored" }
        }
      },
      "InsertBeforeOperation": {
        "type": "object",
        "required": ["operationId", "type", "target", "edit"],
        "properties": {
          "operationId": { "type": "string" },
          "type": { "const": "insert_before" },
          "target": { "$ref": "#/components/schemas/EditTarget" },
          "reason": { "type": "string" },
          "edit": { "$ref": "#/components/schemas/EditPayloadInsert" }
        }
      },
      "InsertAfterOperation": {
        "type": "object",
        "required": ["operationId", "type", "target", "edit"],
        "properties": {
          "operationId": { "type": "string" },
          "type": { "const": "insert_after" },
          "target": { "$ref": "#/components/schemas/EditTarget" },
          "reason": { "type": "string" },
          "edit": { "$ref": "#/components/schemas/EditPayloadInsert" }
        }
      },
      "CreateFileOperation": {
        "type": "object",
        "required": ["operationId", "type", "target", "edit"],
        "properties": {
          "operationId": { "type": "string" },
          "type": { "const": "create_file" },
          "target": { "$ref": "#/components/schemas/EditTarget" },
          "reason": { "type": "string" },
          "edit": { "$ref": "#/components/schemas/EditPayloadFile" }
        }
      },
      "ReplaceFileOperation": {
        "type": "object",
        "required": ["operationId", "type", "target", "edit"],
        "properties": {
          "operationId": { "type": "string" },
          "type": { "const": "replace_file" },
          "target": { "$ref": "#/components/schemas/EditTarget" },
          "reason": { "type": "string" },
          "edit": { "$ref": "#/components/schemas/EditPayloadFile" }
        }
      },
      "EditOperation": {
        "oneOf": [
          { "$ref": "#/components/schemas/ReplaceExactOperation" },
          { "$ref": "#/components/schemas/ReplaceAnchoredOperation" },
          { "$ref": "#/components/schemas/InsertBeforeOperation" },
          { "$ref": "#/components/schemas/InsertAfterOperation" },
          { "$ref": "#/components/schemas/CreateFileOperation" },
          { "$ref": "#/components/schemas/ReplaceFileOperation" }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "replace_exact": "#/components/schemas/ReplaceExactOperation",
            "replace_anchored": "#/components/schemas/ReplaceAnchoredOperation",
            "insert_before": "#/components/schemas/InsertBeforeOperation",
            "insert_after": "#/components/schemas/InsertAfterOperation",
            "create_file": "#/components/schemas/CreateFileOperation",
            "replace_file": "#/components/schemas/ReplaceFileOperation"
          }
        }
      },
      "ContextInput": {
        "type": "object",
        "required": ["projectKey"],
        "properties": {
          "projectKey": { "type": "string" },
          "snapshotId": { "type": "string", "description": "Defaults to latest READY snapshot" },
          "purpose": { "type": "string", "maxLength": 300 }
        }
      },
      "AgentBootstrapInput": {
        "type": "object",
        "required": ["projectKey"],
        "properties": {
          "projectKey": { "type": "string" },
          "snapshotId": { "type": "string", "description": "Defaults to the latest READY snapshot" },
          "purpose": { "type": "string", "maxLength": 300 },
          "treePath": { "type": "string", "description": "Optional initial subtree prefix" },
          "treeDepth": { "type": "integer", "minimum": 1, "maximum": 20, "default": 4 }
        }
      },
      "ReadInput": {
        "type": "object",
        "required": ["path"],
        "properties": {
          "path": { "type": "string" },
          "startLine": { "type": "integer", "minimum": 1 },
          "endLine": { "type": "integer", "minimum": 1, "maximum": 1000 }
        }
      },
      "SearchInput": {
        "type": "object",
        "required": ["query"],
        "properties": { "query": { "type": "string", "maxLength": 200 } }
      },
      "TreeInspectInput": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "Optional subtree prefix. Empty string inspects from repository root.", "default": "" },
          "depth": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Maximum relative path depth from the optional prefix." }
        }
      },
      "SymbolSearchInput": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "maxLength": 200 },
          "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }
        }
      },
      "SymbolReferencesInput": {
        "type": "object",
        "required": ["symbolName"],
        "properties": {
          "symbolName": { "type": "string", "maxLength": 200 },
          "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 }
        }
      },
      "EditInput": {
        "type": "object",
        "required": ["contextSessionId"],
        "properties": {
          "contextSessionId": { "type": "string" },
          "title": { "type": "string", "maxLength": 200 }
        }
      },
      "SubmitOperationsInput": {
        "type": "object",
        "required": ["workspaceRevision", "operations"],
        "properties": {
          "workspaceRevision": { "type": "integer", "minimum": 0 },
          "operations": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": { "$ref": "#/components/schemas/EditOperation" }
          }
        }
      },
      "ProjectSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "key": { "type": "string" },
          "name": { "type": "string" },
          "framework": { "type": "string" },
          "language": { "type": "string" },
          "status": { "type": "string" },
          "aiAccessEnabled": { "type": "boolean" },
          "latestSnapshot": { "type": "object", "nullable": true },
          "snapshotCount": { "type": "integer" }
        }
      },
      "DeletedProject": {
        "type": "object",
        "required": ["key", "name", "deletedAt"],
        "properties": {
          "key": { "type": "string" },
          "name": { "type": "string" },
          "deletedAt": { "type": "string", "format": "date-time" }
        }
      },
      "EditingContract": {
        "type": "object",
        "properties": {
          "projectKey": { "type": "string" },
          "contractVersion": { "type": "string" },
          "defaultBranch": { "type": "string" },
          "rules": { "type": "array", "items": { "type": "string" } },
          "requiredChecks": { "type": "array", "items": { "type": "string" } },
          "forbiddenPaths": { "type": "array", "items": { "type": "string" } },
          "protectedPaths": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ArchitectureSummary": {
        "type": "object",
        "properties": {
          "projectKey": { "type": "string" },
          "framework": { "type": "string" },
          "language": { "type": "string" },
          "packageManager": { "type": "string" },
          "layers": { "type": "array", "items": { "type": "string" } },
          "entryPoints": { "type": "array", "items": { "type": "string" } }
        }
      },
      "SearchMatch": {
        "type": "object",
        "properties": {
          "line": { "type": "integer" },
          "text": { "type": "string" }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "objectHash": { "$ref": "#/components/schemas/ObjectHash" },
          "matches": { "type": "array", "items": { "$ref": "#/components/schemas/SearchMatch" } }
        }
      },
      "SymbolMatch": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "snapshotId": { "type": "string" },
          "path": { "type": "string" },
          "name": { "type": "string" },
          "kind": { "type": "string" },
          "line": { "type": "integer" },
          "isExported": { "type": "boolean" }
        }
      },
      "ReferenceMatch": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "line": { "type": "integer" },
          "text": { "type": "string" },
          "sourceRef": { "type": "string" }
        }
      },
      "ContextSession": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "projectId": { "type": "string" },
          "snapshotId": { "type": "string" },
          "purpose": { "type": "string" },
          "status": { "type": "string" },
          "filesRead": { "type": "array", "items": { "type": "string" } },
          "expiresAt": { "type": "string", "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "TreeFile": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "language": { "type": "string", "nullable": true },
          "lineCount": { "type": "integer", "nullable": true },
          "objectHash": { "$ref": "#/components/schemas/ObjectHash" },
          "sizeBytes": { "type": "integer" },
          "isBinary": { "type": "boolean" }
        }
      },
      "ReadCodeResponse": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "snapshotId": { "type": "string" },
          "objectHash": { "$ref": "#/components/schemas/ObjectHash" },
          "lineStart": { "type": "integer" },
          "lineEnd": { "type": "integer" },
          "totalLines": { "type": "integer" },
          "content": { "type": "string" },
          "sourceRef": { "type": "string" }
        }
      },
      "ReadWorkspaceResponse": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "editTransactionId": { "type": "string" },
          "workspaceRevision": { "type": "integer" },
          "objectHash": { "$ref": "#/components/schemas/ObjectHash" },
          "lineStart": { "type": "integer" },
          "lineEnd": { "type": "integer" },
          "totalLines": { "type": "integer" },
          "content": { "type": "string" },
          "sourceRef": { "type": "string" }
        }
      },
      "EditTransaction": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "contextSessionId": { "type": "string" },
          "baseSnapshotId": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string" },
          "workspaceRevision": { "type": "integer" }
        }
      },
      "PreviewDiffResponse": {
        "type": "object",
        "properties": {
          "transactionId": { "type": "string" },
          "workspaceRevision": { "type": "integer" },
          "diff": { "type": "string" },
          "canonicalHash": { "$ref": "#/components/schemas/ObjectHash" }
        }
      },
      "ValidationCheck": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "status": { "type": "string", "enum": ["PASSED", "FAILED", "SKIPPED"] },
          "message": { "type": "string" },
          "exitCode": { "type": "integer" },
          "logsPath": { "type": "string" },
          "durationMs": { "type": "integer" }
        }
      },
      "ValidationResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string", "enum": ["PASSED", "FAILED", "RUNNING"] },
          "executionMode": { "type": "string" },
          "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationCheck" } }
        }
      },
      "PatchArtifact": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "canonicalHash": { "$ref": "#/components/schemas/ObjectHash" },
          "filesChanged": { "type": "integer" },
          "additions": { "type": "integer" },
          "deletions": { "type": "integer" }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } },
      "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } },
      "Forbidden": { "description": "Scope, project, or policy denial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } },
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } },
      "Conflict": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } },
      "PreconditionFailed": { "description": "Hash or revision mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": { "description": "Service health" }
        }
      }
    },
    "/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "security": [],
        "responses": {
          "200": { "description": "Protocol capabilities" }
        }
      }
    },
    "/agent-guide": {
      "get": {
        "operationId": "getAgentGuide",
        "security": [],
        "description": "Public protocol workflow and safety rules for AI clients.",
        "responses": { "200": { "description": "Agent workflow guide" } }
      }
    },
    "/agent-bootstrap": {
      "post": {
        "operationId": "agentBootstrap",
        "description": "Recommended first authenticated operation. Pins a snapshot and returns context, rules, architecture, initial tree, and next actions.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBootstrapInput" } } }
        },
        "responses": {
          "201": { "description": "Complete agent bootstrap bundle" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/projects": {
      "get": {
        "operationId": "listProjects",
        "responses": {
          "200": {
            "description": "Projects in token scope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSummary" } },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/projects/{projectKey}": {
      "delete": {
        "operationId": "deleteProject",
        "description": "Permanently delete a project and all snapshots, contexts, edits, and patches. Requires project:admin scope.",
        "parameters": [{ "$ref": "#/components/parameters/ProjectKey" }],
        "responses": {
          "200": {
            "description": "Deleted project summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/DeletedProject" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/projects/{projectKey}/editing-contract": {
      "get": {
        "operationId": "getEditingContract",
        "parameters": [{ "$ref": "#/components/parameters/ProjectKey" }],
        "responses": {
          "200": {
            "description": "Project editing rules",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/EditingContract" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/projects/{projectKey}/architecture": {
      "get": {
        "operationId": "getProjectArchitecture",
        "parameters": [{ "$ref": "#/components/parameters/ProjectKey" }],
        "responses": {
          "200": {
            "description": "Project architecture summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/ArchitectureSummary" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/projects/{projectKey}/changes": {
      "get": {
        "operationId": "listProjectChanges",
        "description": "List recent draft, validating, finalized, and reviewable change sessions for one project.",
        "parameters": [{ "$ref": "#/components/parameters/ProjectKey" }],
        "responses": {
          "200": {
            "description": "Recent project change sessions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/EditTransaction" } },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/context-sessions": {
      "post": {
        "operationId": "beginCodeContext",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextInput" } } }
        },
        "responses": {
          "201": {
            "description": "Snapshot-pinned context",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/ContextSession" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/context-sessions/{id}/tree": {
      "post": {
        "operationId": "inspectCodeTree",
        "parameters": [{ "$ref": "#/components/parameters/ContextId" }],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreeInspectInput" } } }
        },
        "responses": {
          "200": {
            "description": "Snapshot file tree",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/TreeFile" } },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/context-sessions/{id}/search": {
      "post": {
        "operationId": "searchCode",
        "parameters": [{ "$ref": "#/components/parameters/ContextId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchInput" } } }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/context-sessions/{id}/read": {
      "post": {
        "operationId": "readCode",
        "parameters": [{ "$ref": "#/components/parameters/ContextId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadInput" } } }
        },
        "responses": {
          "200": {
            "description": "Source lines and immutable reference",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/ReadCodeResponse" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "412": { "$ref": "#/components/responses/PreconditionFailed" }
        }
      }
    },
    "/context-sessions/{id}/symbols/search": {
      "post": {
        "operationId": "searchCodeSymbols",
        "parameters": [{ "$ref": "#/components/parameters/ContextId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolSearchInput" } } }
        },
        "responses": {
          "200": {
            "description": "Snapshot symbol index matches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolMatch" } },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/context-sessions/{id}/symbols/references": {
      "post": {
        "operationId": "findCodeReferences",
        "parameters": [{ "$ref": "#/components/parameters/ContextId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolReferencesInput" } } }
        },
        "responses": {
          "200": {
            "description": "Exact source references",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReferenceMatch" } },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/edit-transactions": {
      "post": {
        "operationId": "beginEditTransaction",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditInput" } } }
        },
        "responses": {
          "201": {
            "description": "Editable workspace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/EditTransaction" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/edit-transactions/{id}/operations:batch": {
      "post": {
        "operationId": "submitEditOperations",
        "parameters": [{ "$ref": "#/components/parameters/EditId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitOperationsInput" } } }
        },
        "responses": {
          "200": {
            "description": "Updated workspace revision",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/EditTransaction" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "412": { "$ref": "#/components/responses/PreconditionFailed" }
        }
      }
    },
    "/edit-transactions/{id}/read-workspace": {
      "post": {
        "operationId": "readWorkspaceCode",
        "description": "Read current edit workspace content after operations or failed validation.",
        "parameters": [{ "$ref": "#/components/parameters/EditId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadInput" } } }
        },
        "responses": {
          "200": {
            "description": "Workspace file content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/ReadWorkspaceResponse" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/edit-transactions/{id}/preview": {
      "post": {
        "operationId": "previewCodeDiff",
        "parameters": [{ "$ref": "#/components/parameters/EditId" }],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } }
        },
        "responses": {
          "200": {
            "description": "Canonical unified diff",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/PreviewDiffResponse" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/edit-transactions/{id}/validate": {
      "post": {
        "operationId": "validateCodeEdit",
        "parameters": [{ "$ref": "#/components/parameters/EditId" }],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } }
        },
        "responses": {
          "200": {
            "description": "Validation diagnostics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/ValidationResponse" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/edit-transactions/{id}/finalize": {
      "post": {
        "operationId": "finalizeCodePatch",
        "parameters": [{ "$ref": "#/components/parameters/EditId" }],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } }
        },
        "responses": {
          "201": {
            "description": "Reviewable patch artifact",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/PatchArtifact" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/validations/{id}": {
      "get": {
        "operationId": "getValidation",
        "parameters": [{ "$ref": "#/components/parameters/ValidationId" }],
        "responses": {
          "200": {
            "description": "Validation run details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/ValidationResponse" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  }
}