{
  "openapi": "3.1.0",
  "info": {
    "title": "agent-fs API",
    "version": "0.11.0",
    "description": "A persistent, searchable filesystem for AI agents. agent-fs is to files what agentmail is to email.",
    "license": {
      "name": "MIT",
      "url": "https://github.com/desplega-ai/agent-fs/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:7433",
      "description": "Local development server"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "operationId": "health",
        "tags": [
          "System"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "version": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "version"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/auth/register": {
      "post": {
        "summary": "Register a new user",
        "operationId": "register",
        "tags": [
          "Auth"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "userId": {
                      "type": "string"
                    },
                    "orgId": {
                      "type": "string"
                    },
                    "driveId": {
                      "type": "string"
                    },
                    "apiKey": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "userId",
                    "orgId",
                    "driveId",
                    "apiKey"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/auth/me": {
      "get": {
        "summary": "Get current user info",
        "operationId": "me",
        "tags": [
          "Auth"
        ],
        "responses": {
          "200": {
            "description": "Current user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "id",
                    "email",
                    "createdAt"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/orgs/{orgId}/ops": {
      "post": {
        "summary": "Dispatch a file operation",
        "operationId": "dispatchOp",
        "tags": [
          "Operations"
        ],
        "description": "All file operations go through this single endpoint. The `op` field determines which operation to execute.",
        "parameters": [
          {
            "name": "orgId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Organization ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "title": "write",
                    "description": "Write or overwrite a file. Creates the file if it doesn't exist, or creates a new version. Use expectedVersion for optimistic concurrency. Returns { version, path, size }.",
                    "required": [
                      "op",
                      "path",
                      "content"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "write"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "content": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      },
                      "expectedVersion": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "cat",
                    "description": "Read file content with optional pagination via offset/limit. Returns { content, totalLines, truncated }.",
                    "required": [
                      "op",
                      "path"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "cat"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "offset": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "edit",
                    "description": "Replace a specific string in a file (surgical find-and-replace). Captures the edit intent as a diff summary in version history. Returns { version, path, changes }.",
                    "required": [
                      "op",
                      "path",
                      "old_string",
                      "new_string"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "edit"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "old_string": {
                        "type": "string"
                      },
                      "new_string": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      },
                      "expectedVersion": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "append",
                    "description": "Append content to the end of an existing file. Creates a new version. Returns { version, size }.",
                    "required": [
                      "op",
                      "path",
                      "content"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "append"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "content": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      },
                      "expectedVersion": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "ls",
                    "description": "List immediate children of a directory. Returns { entries } where each entry has name, type (file/directory), size, author, modifiedAt.",
                    "required": [
                      "op"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "ls"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "stat",
                    "description": "Get file metadata without reading content. Returns path, size, contentType, author, currentVersion, createdAt, modifiedAt, isDeleted, embeddingStatus.",
                    "required": [
                      "op",
                      "path"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "stat"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "rm",
                    "description": "Delete a file. Removes from S3, cleans up FTS5 index and vector embeddings. Returns { path, deleted }.",
                    "required": [
                      "op",
                      "path"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "rm"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "expectedVersion": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "mv",
                    "description": "Move or rename a file. Preserves version history at the new path. Returns { from, to, version }.",
                    "required": [
                      "op",
                      "from",
                      "to"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "mv"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "from": {
                        "type": "string"
                      },
                      "to": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      },
                      "expectedVersion": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "cp",
                    "description": "Copy a file using server-side S3 copy. Creates a new version at the destination. Returns { from, to, version }.",
                    "required": [
                      "op",
                      "from",
                      "to"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "cp"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "from": {
                        "type": "string"
                      },
                      "to": {
                        "type": "string"
                      },
                      "expectedVersion": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "tail",
                    "description": "Read the last N lines of a file (default 20). Returns { content, totalLines, truncated }.",
                    "required": [
                      "op",
                      "path"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "tail"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "lines": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "log",
                    "description": "Show version history for a file. Returns { versions } with version number, author, timestamp, operation type, message, and diff summary.",
                    "required": [
                      "op",
                      "path"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "log"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "diff",
                    "description": "Show the diff between two versions of a file. Specify v1 and v2 version numbers. Returns { changes } as add/remove/context hunks.",
                    "required": [
                      "op",
                      "path",
                      "v1",
                      "v2"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "diff"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "v1": {
                        "type": "integer"
                      },
                      "v2": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "revert",
                    "description": "Revert a file to a previous version. Creates a new version with the old content. Returns { version, revertedTo }.",
                    "required": [
                      "op",
                      "path",
                      "version"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "revert"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "version": {
                        "type": "integer"
                      },
                      "expectedVersion": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "recent",
                    "description": "Show recent activity across the drive. Optionally filter by path prefix and time window (since). Returns { entries } with path and version details.",
                    "required": [
                      "op"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "recent"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "since": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "grep",
                    "description": "Search file content using regex pattern within a specific path. Returns matching lines with line numbers. Searches the FTS5 index, not S3 directly.",
                    "required": [
                      "op",
                      "pattern",
                      "path"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "grep"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "pattern": {
                        "type": "string"
                      },
                      "path": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "fts",
                    "description": "Full-text search across all file content using FTS5 tokens. Different from grep (regex) and search (semantic). Returns { matches } with path, snippet, and rank.",
                    "required": [
                      "op",
                      "pattern"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "fts"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "pattern": {
                        "type": "string"
                      },
                      "path": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "search",
                    "description": "Hybrid search combining semantic (vector) and keyword (FTS5) matching. Best for natural language queries. Degrades to keyword-only without an embedding provider.",
                    "required": [
                      "op",
                      "query"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "search"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "query": {
                        "type": "string"
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "vec-search",
                    "description": "Vector-only semantic search using embeddings. Returns results ranked by cosine similarity. Requires an embedding provider (OPENAI_API_KEY, GEMINI_API_KEY, or local).",
                    "required": [
                      "op",
                      "query"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "vec-search"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "query": {
                        "type": "string"
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "reindex",
                    "description": "Re-index files with failed or missing FTS5/embedding entries. Optionally scope to a path prefix. Use after bulk writes or provider changes.",
                    "required": [
                      "op"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "reindex"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "tree",
                    "description": "Recursively list all files and directories. Use depth to limit recursion. Returns a nested tree structure with name, type, size, and children.",
                    "required": [
                      "op"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "tree"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "depth": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "glob",
                    "description": "Find files by name pattern. Use `*.md` for root-level files only, `**/*.md` for recursive matching across all subdirectories. Supports `*` (any chars except /), `?` (single char), `**` (any path depth). Optionally scope to a path prefix. Returns { matches } with path, size, and modifiedAt.",
                    "required": [
                      "op",
                      "pattern"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "glob"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "pattern": {
                        "type": "string"
                      },
                      "path": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "sql",
                    "description": "Run a DuckDB SQL query over documents stored in the drive. Reference documents directly by path string literal (e.g. SELECT * FROM '/data/sales.csv') or bind them as named tables via `tables` ({ name: path } or { name: { path, format } } to override format detection). Supports csv, tsv, parquet, xlsx, json, ndjson/jsonl (each also .gz except parquet/xlsx), sqlite (.db/.sqlite/.sqlite3, tables exposed as name.tablename), and .duckdb files. Queries run sandboxed: no filesystem or network access beyond the bound documents. Returns { columns, rows, rowCount, truncated, files, elapsedMs }.",
                    "required": [
                      "op",
                      "query"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "sql"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "query": {
                        "type": "string"
                      },
                      "tables": {
                        "type": "object",
                        "additionalProperties": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "path": {
                                  "type": "string"
                                },
                                "format": {
                                  "type": "string",
                                  "enum": [
                                    "csv",
                                    "tsv",
                                    "parquet",
                                    "xlsx",
                                    "json",
                                    "ndjson",
                                    "sqlite",
                                    "duckdb"
                                  ]
                                }
                              },
                              "required": [
                                "path"
                              ],
                              "additionalProperties": false
                            }
                          ]
                        }
                      },
                      "maxRows": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "signed-url",
                    "description": "Generate a temporary presigned URL for direct file download. Default expiry is 24 hours (86400 seconds). The URL requires no authentication. Returns { url, path, expiresIn, expiresAt }.",
                    "required": [
                      "op",
                      "path"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "signed-url"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "expiresIn": {
                        "type": "integer",
                        "minimum": 60,
                        "maximum": 604800
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-add",
                    "description": "Add a comment to a file. Supports line ranges and threading via parentId. Replies auto-resolve path from parent. Returns { id, path, body, author, createdAt }.",
                    "required": [
                      "op",
                      "body"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-add"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "body": {
                        "type": "string"
                      },
                      "parentId": {
                        "type": "string"
                      },
                      "lineStart": {
                        "type": "integer"
                      },
                      "lineEnd": {
                        "type": "integer"
                      },
                      "quotedContent": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-list",
                    "description": "List comments on a file. Filter by path, resolved state, or parentId. Defaults to unresolved root comments. Returns { comments } with inline replies.",
                    "required": [
                      "op"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-list"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "path": {
                        "type": "string"
                      },
                      "parentId": {
                        "type": "string"
                      },
                      "resolved": {
                        "type": "boolean"
                      },
                      "orgId": {
                        "type": "string"
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "offset": {
                        "type": "integer",
                        "minimum": 0
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-get",
                    "description": "Get a single comment by ID with all its replies. Returns { comment, replies }.",
                    "required": [
                      "op",
                      "id"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-get"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "id": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-update",
                    "description": "Update a comment's body. Only the original author can update. Returns { id, body, updatedAt }.",
                    "required": [
                      "op",
                      "id",
                      "body"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-update"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "id": {
                        "type": "string"
                      },
                      "body": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-delete",
                    "description": "Soft-delete a comment. Only the original author can delete. Deleting a root comment also soft-deletes its replies. Returns { deleted }.",
                    "required": [
                      "op",
                      "id"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-delete"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "id": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-resolve",
                    "description": "Resolve or reopen a root comment. Set resolved=true to resolve, resolved=false to reopen. Only root comments can be resolved. Returns { id, resolved, resolvedBy, resolvedAt }.",
                    "required": [
                      "op",
                      "id",
                      "resolved"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-resolve"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "id": {
                        "type": "string"
                      },
                      "resolved": {
                        "type": "boolean"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-notification-list",
                    "description": "List comment notifications for the current user in the active drive. Returns { notifications, unreadCount }.",
                    "required": [
                      "op"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-notification-list"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "unreadOnly": {
                        "type": "boolean"
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100
                      },
                      "offset": {
                        "type": "integer",
                        "minimum": 0
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "title": "comment-notification-read",
                    "description": "Mark selected comment notification IDs, or all comment notifications in the active drive, as read. Returns { markedRead }.",
                    "required": [
                      "op"
                    ],
                    "properties": {
                      "op": {
                        "type": "string",
                        "const": "comment-notification-read"
                      },
                      "driveId": {
                        "type": "string",
                        "description": "Target drive ID (optional, uses default drive)"
                      },
                      "ids": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "minItems": 1,
                        "maxItems": 100
                      },
                      "all": {
                        "type": "boolean",
                        "enum": [
                          true
                        ]
                      }
                    },
                    "additionalProperties": false
                  }
                ],
                "discriminator": {
                  "propertyName": "op"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation result (varies by op)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Response shape depends on the operation. See each op's description for details."
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied (RBAC)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "File or resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key obtained from /auth/register"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ]
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}