{
  "openapi": "3.0.0",
  "info": {
    "title": "slskr HTTP API",
    "description": "HTTP API for the slskr Soulseek client",
    "version": "1.0.0",
    "contact": {
      "name": "slskr",
      "url": "https://github.com/snapetech/slskr"
    },
    "license": {
      "name": "AGPL-3.0-only",
      "url": "https://www.gnu.org/licenses/agpl-3.0.html"
    }
  },
  "servers": [
    {
      "url": "http://127.0.0.1:5030",
      "description": "Local development server"
    },
    {
      "url": "https://api.example.com",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health check",
        "description": "Check if server is running",
        "operationId": "getHealth",
        "security": [],
        "tags": ["Health"],
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/api/version": {
      "get": {
        "summary": "Get version",
        "operationId": "getVersion",
        "security": [],
        "tags": ["Info"],
        "responses": {
          "200": {
            "description": "Version information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionInfo"
                }
              }
            }
          }
        }
      }
    },
    "/api/config": {
      "get": {
        "summary": "Get configuration",
        "operationId": "getConfig",
        "tags": ["Configuration"],
        "responses": {
          "200": {
            "description": "Current configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Configuration"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "summary": "Get statistics",
        "operationId": "getStats",
        "tags": ["Statistics"],
        "responses": {
          "200": {
            "description": "Server statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Statistics"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/api/capabilities": {
      "get": {
        "summary": "Get capabilities",
        "description": "List supported API capabilities",
        "operationId": "getCapabilities",
        "security": [],
        "tags": ["Capabilities"],
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "Response format",
            "schema": {
              "type": "string",
              "enum": ["json", "csv"],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          }
        }
      }
    },
    "/api/searches": {
      "get": {
        "summary": "List searches as a slskd-compatible array",
        "operationId": "listSearches",
        "tags": ["Search"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Search array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Search"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      },
      "post": {
        "summary": "Create search",
        "operationId": "createSearch",
        "tags": ["Search"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Search created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenError"
          }
        }
      }
    },
    "/api/searches/records": {
      "get": {
        "summary": "List searches with slskr metadata envelope",
        "operationId": "listSearchRecords",
        "tags": ["Search"],
        "responses": {
          "200": {
            "description": "Search record envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchRecordList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/api/searches/{id}": {
      "get": {
        "summary": "Get search details",
        "operationId": "getSearchDetails",
        "tags": ["Search"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer" }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Search details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/api/messages": {
      "get": {
        "summary": "List messages",
        "operationId": "listMessages",
        "tags": ["Messages"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Messages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "messages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Message"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      },
      "post": {
        "summary": "Send message",
        "operationId": "sendMessage",
        "tags": ["Messages"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageSendRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenError"
          }
        }
      }
    },
    "/api/transfers": {
      "get": {
        "summary": "List transfers",
        "operationId": "listTransfers",
        "tags": ["Transfers"],
        "parameters": [
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["upload", "download"]
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["active", "completed", "failed", "cancelled"]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transfers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Transfer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      },
      "post": {
        "summary": "Create transfer",
        "operationId": "createTransfer",
        "tags": ["Transfers"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Transfer created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transfer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenError"
          },
          "409": {
            "$ref": "#/components/responses/ConflictError"
          }
        }
      }
    },
    "/api/transfers/{id}": {
      "get": {
        "summary": "Get transfer details",
        "operationId": "getTransfer",
        "tags": ["Transfers"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transfer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "delete": {
        "summary": "Cancel transfer",
        "operationId": "cancelTransfer",
        "tags": ["Transfers"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "204": {
            "description": "Transfer cancelled"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/api/batch": {
      "post": {
        "summary": "Execute batch operations",
        "description": "Execute multiple operations in a single request",
        "operationId": "batchOperations",
        "tags": ["Batch"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenError"
          }
        }
      }
    },
    "/api/events": {
      "get": {
        "summary": "List events as a slskd-compatible array",
        "operationId": "listEvents",
        "tags": ["Events"],
        "responses": {
          "200": {
            "description": "Event array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Event"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/api/events/records": {
      "get": {
        "summary": "List events with slskr metadata envelope",
        "operationId": "listEventRecords",
        "tags": ["Events"],
        "responses": {
          "200": {
            "description": "Event record envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventRecordList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["ok", "unhealthy"]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["status", "timestamp"]
      },
      "VersionInfo": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "protocol": {
            "type": "object",
            "properties": {
              "client_name": {
                "type": "string"
              },
              "major": {
                "type": "integer"
              },
              "minor": {
                "type": "integer"
              }
            },
            "required": ["client_name", "major", "minor"]
          }
        },
        "required": ["name", "version", "protocol"]
      },
      "Configuration": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "server_address": {
            "type": "string"
          },
          "shared_directories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "transfer_max_active": {
            "type": "integer"
          }
        }
      },
      "Statistics": {
        "type": "object",
        "properties": {
          "total_size": {
            "type": "integer"
          },
          "file_count": {
            "type": "integer"
          },
          "uploads": {
            "type": "integer"
          },
          "downloads": {
            "type": "integer"
          },
          "transfer_speeds": {
            "type": "object",
            "properties": {
              "up": {
                "type": "integer"
              },
              "down": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Capabilities": {
        "type": "object",
        "properties": {
          "app": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "network": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "storage": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "experimental": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["app", "network", "storage"]
      },
      "Search": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "token": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          },
          "searchText": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["active", "completed", "expired", "failed"]
          },
          "state": {
            "type": "string"
          },
          "isComplete": {
            "type": "boolean"
          },
          "fileCount": {
            "type": "integer"
          },
          "lockedFileCount": {
            "type": "integer"
          },
          "responseCount": {
            "type": "integer"
          },
          "responses": {
            "type": "array"
          },
          "results": {
            "type": "array"
          },
          "result_count": {
            "type": "integer"
          },
          "startedAt": {
            "type": "string"
          },
          "endedAt": {
            "type": "string",
            "nullable": true
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["id", "query", "searchText", "status", "state", "isComplete", "fileCount", "lockedFileCount", "responseCount", "responses"]
      },
      "SearchRecordList": {
        "type": "object",
        "properties": {
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Search"
            }
          },
          "count": {
            "type": "integer"
          },
          "filtered_count": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "limit": {
            "type": "integer",
            "nullable": true
          },
          "next_token": {
            "type": "integer"
          }
        },
        "required": ["entries", "count", "filtered_count", "offset", "next_token"]
      },
      "SearchDetails": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Search"
          },
          {
            "type": "object",
            "properties": {
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          }
        ]
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          },
          "bitrate": {
            "type": "integer"
          },
          "length": {
            "type": "integer"
          }
        },
        "required": ["username", "filename", "size"]
      },
      "SearchCreateRequest": {
        "type": "object",
        "description": "Provide either query or slskd-compatible searchText.",
        "properties": {
          "query": {
            "type": "string"
          },
          "searchText": {
            "type": "string"
          },
          "room": {
            "type": "string",
            "nullable": true
          },
          "target": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "type": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "resource": {
            "type": "string"
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "integer"
          }
        },
        "required": ["id", "type", "kind", "resource", "createdAt"]
      },
      "EventRecordList": {
        "type": "object",
        "properties": {
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "count": {
            "type": "integer"
          },
          "filtered_count": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "limit": {
            "type": "integer",
            "nullable": true
          }
        },
        "required": ["entries", "count", "filtered_count", "offset"]
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "sender": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["id", "sender", "content", "timestamp"]
      },
      "MessageSendRequest": {
        "type": "object",
        "properties": {
          "recipient": {
            "type": "string"
          },
          "content": {
            "type": "string"
          }
        },
        "required": ["recipient", "content"]
      },
      "Transfer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": ["upload", "download"]
          },
          "status": {
            "type": "string",
            "enum": ["active", "completed", "failed", "cancelled"]
          },
          "peer_username": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "size": {
            "type": "integer",
            "nullable": true
          },
          "bytes_transferred": {
            "type": "integer"
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "direction",
          "status",
          "peer_username",
          "filename",
          "bytes_transferred",
          "started_at"
        ]
      },
      "TransferCreateRequest": {
        "type": "object",
        "properties": {
          "direction": {
            "type": "string",
            "enum": ["upload", "download"]
          },
          "peer_username": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          }
        },
        "required": ["direction", "peer_username", "filename"]
      },
      "BatchOperation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "method": {
            "type": "string",
            "enum": ["GET", "POST", "PUT", "DELETE"]
          },
          "path": {
            "type": "string"
          },
          "body": {
            "type": "object"
          }
        },
        "required": ["id", "method", "path"]
      },
      "BatchRequest": {
        "type": "object",
        "properties": {
          "operations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchOperation"
            }
          }
        },
        "required": ["operations"]
      },
      "BatchResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "body": {
            "type": "object"
          }
        },
        "required": ["id", "status", "body"]
      },
      "BatchResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchResult"
            }
          },
          "total_time_ms": {
            "type": "integer"
          }
        },
        "required": ["results", "total_time_ms"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "details": {
            "type": "string"
          }
        },
        "required": ["error"]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Opaque"
      }
    },
    "responses": {
      "BadRequestError": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnauthorizedError": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ForbiddenError": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFoundError": {
        "description": "Not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ConflictError": {
        "description": "Conflict",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}