ollie-httpgw/openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "ollie-httpgw",
    "description": "HTTP gateway for the ollie 9P server.",
    "version": "1.0.0"
  },
  "paths": {
    "/{path}": {
      "parameters": [
        {
          "name": "path",
          "in": "path",
          "required": true,
          "description": "9P file or directory path (may contain slashes for nested paths)",
          "schema": { "type": "string" },
          "example": "s/idx"
        }
      ],
      "get": {
        "summary": "Read file or list directory",
        "description": "Returns parsed file content as a JSON object or array, or a directory listing.",
        "responses": {
          "200": {
            "description": "File content or directory listing",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "title": "Key-value file", "type": "object", "additionalProperties": { "type": "string" } },
                    { "title": "List file", "type": "array", "items": { "type": "string" } },
                    { "title": "Session index", "type": "array", "items": { "$ref": "#/components/schemas/IdxEntry" } },
                    { "title": "Directory", "type": "array", "items": { "$ref": "#/components/schemas/DirEntry" } }
                  ]
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      },
      "head": {
        "summary": "Stat file or directory",
        "description": "Returns 9P metadata in response headers. No body.",
        "responses": {
          "200": {
            "description": "Stat headers set",
            "headers": { "$ref": "#/components/headers/StatHeaders" }
          },
          "404": { "$ref": "#/components/responses/Error" }
        }
      },
      "post": {
        "summary": "Write to file or trigger action",
        "description": "Writes a JSON object to a file, serialized as key=value lines. Used for session creation (POST /s/new), config updates (POST /s/{id}/cfg), and control actions (POST /s/{id}/ctl, /s/{id}/prompt, /s/{id}/fifo.in).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bytes written",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bytes_written": { "type": "integer" }
                  },
                  "required": ["bytes_written"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "405": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" }
        }
      },
      "delete": {
        "summary": "Remove file or session",
        "description": "Removes the file or kills the session at the given path.",
        "responses": {
          "204": { "description": "Removed" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      },
      "patch": {
        "summary": "Rename file or session",
        "description": "Renames the file or session via 9P wstat.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "New name" }
                },
                "required": ["name"]
              }
            }
          }
        },
        "responses": {
          "204": { "description": "Renamed" },
          "400": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" }
        }
      },
      "options": {
        "summary": "Describe available operations",
        "description": "Returns the allowed HTTP methods and a description of each operation for this path.",
        "responses": {
          "200": {
            "description": "Available methods",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OptionsResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "IdxEntry": {
        "type": "object",
        "properties": {
          "id":      { "type": "string" },
          "state":   { "type": "string" },
          "cwd":     { "type": "string" },
          "backend": { "type": "string" },
          "model":   { "type": "string" }
        },
        "required": ["id", "state", "cwd", "backend", "model"]
      },
      "DirEntry": {
        "type": "object",
        "properties": {
          "name":   { "type": "string" },
          "size":   { "type": "integer", "format": "uint64" },
          "mode":   { "type": "integer", "format": "uint32" },
          "mtime":  { "type": "integer", "format": "uint32" },
          "is_dir": { "type": "boolean" }
        },
        "required": ["name", "size", "mode", "mtime", "is_dir"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        },
        "required": ["error"]
      },
      "OptionsResponse": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "methods": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        },
        "required": ["path", "methods"]
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "headers": {
      "StatHeaders": {
        "description": "9P stat fields returned as response headers",
        "X-9p-Name":  { "schema": { "type": "string" } },
        "X-9p-Size":  { "schema": { "type": "integer" } },
        "X-9p-Mode":  { "schema": { "type": "string" } },
        "X-9p-Mtime": { "schema": { "type": "integer" } },
        "X-9p-Type":  { "schema": { "type": "string", "enum": ["file", "dir"] } }
      }
    }
  }
}