{
  "openapi": "3.0.3",
  "info": {
    "title": "openmamba packaging API",
    "description": "REST API for querying openmamba Linux distribution repositories and packages",
    "version": "3.0.6"
  },
  "servers": [{"url": "."}],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token with access level bitmask (bit 0: read social_log, bit 1: write social_log)"
      }
    }
  },
  "paths": {
    "/repositories": {
      "get": {
        "summary": "List all repositories",
        "operationId": "getRepositories",
        "responses": {
          "200": {
            "description": "List of repositories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "tag": {"type": "string"},
                      "archs": {"type": "array", "items": {"type": "string"}},
                      "description": {"type": "string"},
                      "parents": {"type": "array", "items": {"type": "string"}}
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/repository/{tag}": {
      "get": {
        "summary": "List packages in a repository",
        "operationId": "getRepositoryPackages",
        "parameters": [
          {"name": "tag", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Repository tag (e.g. base)"},
          {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Search term to filter by name, summary or description"},
          {"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 100}, "description": "Number of results per page"},
          {"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}, "description": "Page number"},
          {"name": "sort", "in": "query", "schema": {"type": "string", "enum": ["name", "buildtime"], "default": "name"}, "description": "Sort field"},
          {"name": "order", "in": "query", "schema": {"type": "string", "enum": ["asc", "desc"], "default": "asc"}, "description": "Sort order"},
          {"name": "arch", "in": "query", "schema": {"type": "string"}, "description": "Comma-separated list of architectures to include (e.g. src,x86_64,aarch64,i586). Default: all"},
          {"name": "add", "in": "query", "schema": {"type": "string"}, "description": "Comma-separated list of additional fields. Supported: changelog (adds last 2 changelog entries to each source package), children (adds built binary packages per arch to each source package), problems (adds warnings and needrebuild info for each source package), updates (adds versions of the same source package found in parent repositories, ordered from nearest), parents (merges packages from all parent repositories into the result, with higher-level repository packages taking precedence over same-named packages from parents)"}
        ],
        "responses": {
          "200": {
            "description": "Paginated list of packages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object",
                      "properties": {
                        "repository": {"type": "string"},
                        "per_page": {"type": "integer"},
                        "page": {"type": "integer"},
                        "q": {"type": "string"},
                        "sort": {"type": "string"},
                        "order": {"type": "string"},
                        "arch": {"type": "array", "items": {"type": "string"}},
                        "total": {"type": "integer"},
                        "pages": {"type": "integer"},
                        "from": {"type": "integer"},
                        "to": {"type": "integer"}
                      }
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "repositories": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "index": {"type": "integer"},
                              "name": {"type": "string"},
                              "archs": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "object",
                                  "properties": {
                                    "timestamp": {"type": "string", "format": "date-time"},
                                    "packages": {"type": "integer"},
                                    "size": {"type": "integer"}
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "packages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {"type": "string"},
                          "arch": {"type": "string"},
                          "epoch": {"type": "integer"},
                          "version": {"type": "string"},
                          "release": {"type": "string"},
                          "summary": {"type": "string"},
                          "buildtime": {"type": "string", "format": "date-time"},
                          "updates": {
                            "type": "array",
                            "description": "Versions of this source package in parent repositories (nearest first). Present only for src packages when add=updates is requested.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "repository": {"type": "string"},
                                "version": {"type": "string"},
                                "release": {"type": "string"}
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/package/{repository}/{package}": {
      "get": {
        "summary": "Get source package details",
        "operationId": "getPackageSourceDetails",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "package", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "add", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Comma-separated list of extra fields to include. Supported: buildrequires, providers (adds providers to each buildrequires entry, requires add=buildrequires), changelog, requiredby, recommendedby, buildrequiredby, files, problems"},
          {"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 100}, "description": "Number of results per page for paginated add sections (buildrequiredby)"},
          {"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}, "description": "Page number for paginated add sections (buildrequiredby)"}
        ],
        "responses": {
          "200": {
            "description": "Source package details including children and optional sections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "integer"},
                    "name": {"type": "string"},
                    "summary": {"type": "string"},
                    "epoch": {"type": "string"},
                    "version": {"type": "string"},
                    "release": {"type": "string"},
                    "description": {"type": "string"},
                    "group": {"type": "string"},
                    "license": {"type": "string"},
                    "url": {"type": "string"},
                    "size": {"type": "integer"},
                    "maintainer": {"type": "string"},
                    "buildtime": {"type": "string", "format": "date-time"},
                    "download_url": {"type": "string"},
                    "source_url": {"type": "string"},
                    "buildrequires": {"type": "array", "items": {"type": "object"}, "description": "Build dependencies (present only when add=buildrequires); each entry may include providers when add=providers"},
                    "children": {"type": "object"},
                    "changelog": {"type": "array", "items": {"type": "object"}, "description": "Changelog entries (present only when add=changelog)"},
                    "requiredby": {"type": "object", "description": "Source packages requiring any provide of this source, grouped by source name and arch (present only when add=requiredby)"},
                    "recommendedby": {"type": "object", "description": "Source packages recommending any provide of this source, grouped by source name and arch (present only when add=recommendedby)"},
                    "query": {"type": "object", "description": "Pagination metadata (present when add=buildrequiredby)", "properties": {"per_page": {"type": "integer"}, "page": {"type": "integer"}, "buildrequiredby": {"type": "object", "properties": {"total": {"type": "integer"}, "pages": {"type": "integer"}, "from": {"type": "integer"}, "to": {"type": "integer"}}}}},
                    "buildrequiredby": {"type": "object", "description": "Source packages that have a BuildRequires matching any provide of this source, grouped by source name (present only when add=buildrequiredby); paginated by source name"},
                    "files": {"type": "array", "items": {"type": "string"}, "description": "Source file names from the SRPM (present only when add=files)"},
                    "problems": {"type": "object", "description": "Warnings, needrebuild and needport for this source package (present only when add=problems)", "properties": {"warnings": {"type": "array", "items": {"type": "object"}}, "needrebuild": {"type": "array", "items": {"type": "object"}}, "needport": {"type": "array", "items": {"type": "object"}}}}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/package/{repository}/{package}/{arch}": {
      "get": {
        "summary": "Get binary package details",
        "operationId": "getPackageDetails",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "package", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "arch", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Architecture (e.g. x86_64, aarch64, i586)"},
          {"name": "add", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Comma-separated list of extra fields to include. Supported: provides, requires, recommends, providers (adds providers to each requires/recommends entry, requires add=requires or add=recommends), requiredby, recommendedby, files"},
          {"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 100}, "description": "Number of results per page for paginated add sections"},
          {"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}, "description": "Page number for paginated add sections"}
        ],
        "responses": {
          "200": {
            "description": "Binary package details with optional sections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "integer"},
                    "name": {"type": "string"},
                    "summary": {"type": "string"},
                    "epoch": {"type": "string"},
                    "version": {"type": "string"},
                    "release": {"type": "string"},
                    "description": {"type": "string"},
                    "group": {"type": "string"},
                    "arch": {"type": "string"},
                    "size": {"type": "integer"},
                    "source": {"type": "object"},
                    "download_url": {"type": "string"},
                    "brothers": {"type": "array", "items": {"type": "string"}},
                    "obsoletes": {"type": "array", "items": {"type": "object"}},
                    "provides": {"type": "array", "items": {"type": "object"}, "description": "Capabilities provided by this package (present only when add=provides)"},
                    "requires": {"type": "array", "items": {"type": "object"}, "description": "Dependencies of this package (present only when add=requires); each entry may include providers when add=providers"},
                    "recommends": {"type": "array", "items": {"type": "object"}, "description": "Recommended dependencies of this package (present only when add=recommends); each entry may include providers when add=providers"},
                    "query": {"type": "object", "description": "Pagination metadata (present only when any add section is requested)", "properties": {
                      "per_page": {"type": "integer"},
                      "page": {"type": "integer"},
                      "requiredby": {"type": "object", "properties": {"total": {"type": "integer"}, "pages": {"type": "integer"}, "from": {"type": "integer"}, "to": {"type": "integer"}}},
                      "recommendedby": {"type": "object", "properties": {"total": {"type": "integer"}, "pages": {"type": "integer"}, "from": {"type": "integer"}, "to": {"type": "integer"}}},
                      "files": {"type": "object", "properties": {"total": {"type": "integer"}, "pages": {"type": "integer"}, "from": {"type": "integer"}, "to": {"type": "integer"}}}
                    }},
                    "requiredby": {"type": "array", "items": {"type": "string"}, "description": "Packages that require this package (present only when add=requiredby)"},
                    "recommendedby": {"type": "array", "items": {"type": "string"}, "description": "Packages that recommend this package (present only when add=recommendedby)"},
                    "files": {"type": "array", "items": {"type": "object", "properties": {"path": {"type": "string"}}}, "description": "Files in the package (present only when add=files)"}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/providers/{repository}/{requirement}": {
      "get": {
        "summary": "Find providers for a requirement (any version)",
        "operationId": "getProviders",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "requirement", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Capability name to search for"}
        ],
        "responses": {
          "200": {
            "description": "List of packages providing the requirement, grouped by arch",
            "content": {"application/json": {"schema": {"type": "object"}}}
          }
        }
      }
    },
    "/providers/{repository}/{requirement}/{arch}": {
      "get": {
        "summary": "Find providers for a requirement filtered by arch",
        "operationId": "getProvidersForArch",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "requirement", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Capability name to search for"},
          {"name": "arch", "in": "path", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "Flat list of packages providing the requirement for the given arch",
            "content": {"application/json": {"schema": {"type": "array"}}}
          }
        }
      }
    },
    "/requirers/{repository}/{requirement}": {
      "get": {
        "summary": "Find packages requiring a capability (any version)",
        "operationId": "getRequirers",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "requirement", "in": "path", "required": true, "schema": {"type": "string"}, "description": "URL-encoded capability name or file path to search for"}
        ],
        "responses": {
          "200": {
            "description": "List of packages requiring the capability, grouped by arch",
            "content": {"application/json": {"schema": {"type": "object"}}}
          }
        }
      }
    },
    "/requirers/{repository}/{requirement}/{arch}": {
      "get": {
        "summary": "Find packages requiring a capability filtered by arch",
        "operationId": "getRequirersForArch",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "requirement", "in": "path", "required": true, "schema": {"type": "string"}, "description": "URL-encoded capability name or file path to search for"},
          {"name": "arch", "in": "path", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "Flat list of packages requiring the capability for the given arch",
            "content": {"application/json": {"schema": {"type": "array"}}}
          }
        }
      }
    },
    "/recommenders/{repository}/{requirement}": {
      "get": {
        "summary": "Find packages recommending a capability (any version)",
        "operationId": "getRecommenders",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "requirement", "in": "path", "required": true, "schema": {"type": "string"}, "description": "URL-encoded capability name or file path to search for"}
        ],
        "responses": {
          "200": {
            "description": "List of packages recommending the capability, grouped by arch",
            "content": {"application/json": {"schema": {"type": "object"}}}
          }
        }
      }
    },
    "/recommenders/{repository}/{requirement}/{arch}": {
      "get": {
        "summary": "Find packages recommending a capability filtered by arch",
        "operationId": "getRecommendersForArch",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "requirement", "in": "path", "required": true, "schema": {"type": "string"}, "description": "URL-encoded capability name or file path to search for"},
          {"name": "arch", "in": "path", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "Flat list of packages recommending the capability for the given arch",
            "content": {"application/json": {"schema": {"type": "array"}}}
          }
        }
      }
    },
    "/buildrequirers/{repository}/{requirement}": {
      "get": {
        "summary": "Find source packages build-requiring a capability (any version)",
        "operationId": "getBuildRequirers",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "requirement", "in": "path", "required": true, "schema": {"type": "string"}, "description": "URL-encoded capability name to search for"}
        ],
        "responses": {
          "200": {
            "description": "List of source packages build-requiring the capability",
            "content": {"application/json": {"schema": {"type": "object"}}}
          }
        }
      }
    },
    "/file_providers/{repository}/{filepath}/{arch}": {
      "get": {
        "summary": "Find packages providing a file path",
        "operationId": "getFileProviders",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}},
          {"name": "filepath", "in": "path", "required": true, "schema": {"type": "string"}, "description": "URL-encoded file path (e.g. %2Fbin%2Fbash)"},
          {"name": "arch", "in": "path", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "List of packages providing the file",
            "content": {"application/json": {"schema": {"type": "object"}}}
          }
        }
      }
    },
    "/problems/{repository}": {
      "get": {
        "summary": "List repository problems",
        "operationId": "getRepositoryProblems",
        "parameters": [
          {"name": "repository", "in": "path", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "List of warnings and packages needing rebuild",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "repositories": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "index": {"type": "integer"},
                              "name": {"type": "string"},
                              "archs": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "object",
                                  "properties": {
                                    "timestamp": {"type": "string", "format": "date-time"},
                                    "packages": {"type": "integer"},
                                    "size": {"type": "integer"}
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "repository": {"type": "string"},
                          "arch": {"type": "string"},
                          "name": {"type": "string"},
                          "srcname": {"type": "string", "description": "Source package name the binary package belongs to"},
                          "text": {"type": "string"},
                          "relname": {"type": "string", "description": "Name of the related package involved in the warning"},
                          "relarch": {"type": "string", "description": "Architecture of the related package"},
                          "relrepository": {"type": "string", "description": "Repository of the related package"}
                        }
                      }
                    },
                    "needrebuild": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {"type": "string"},
                          "torebuild": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {"type": "string"},
                                "arch": {"type": "string", "description": "Repository architecture"},
                                "buildarch": {"type": "string", "description": "Package build architecture"},
                                "provider": {"type": "string", "description": "Binary package name that triggered the rebuild need"}
                              }
                            }
                          }
                        }
                      }
                    },
                    "needport": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {"type": "string"},
                          "archs": {"type": "array", "items": {"type": "string"}, "description": "Repository architectures requiring a port"}
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Search packages across all repositories",
        "operationId": "getSearch",
        "parameters": [
          {"name": "q", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Search term matched against name, summary and description"},
          {"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 100}, "description": "Number of results per page"},
          {"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}, "description": "Page number"},
          {"name": "sort", "in": "query", "schema": {"type": "string", "enum": ["name", "buildtime"], "default": "name"}, "description": "Sort field"},
          {"name": "order", "in": "query", "schema": {"type": "string", "enum": ["asc", "desc"], "default": "asc"}, "description": "Sort order"},
          {"name": "arch", "in": "query", "schema": {"type": "string"}, "description": "Comma-separated list of architectures to include (e.g. src,x86_64,aarch64,i586). Default: all"}
        ],
        "responses": {
          "200": {
            "description": "Paginated search results across all repositories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object",
                      "properties": {
                        "per_page": {"type": "integer"},
                        "page": {"type": "integer"},
                        "q": {"type": "string"},
                        "sort": {"type": "string"},
                        "order": {"type": "string"},
                        "arch": {"type": "array", "items": {"type": "string"}},
                        "total": {"type": "integer"},
                        "pages": {"type": "integer"},
                        "from": {"type": "integer"},
                        "to": {"type": "integer"}
                      }
                    },
                    "packages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "repository": {"type": "string"},
                          "name": {"type": "string"},
                          "arch": {"type": "string"},
                          "version": {"type": "string"},
                          "release": {"type": "string"},
                          "summary": {"type": "string"},
                          "buildtime": {"type": "string", "format": "date-time"}
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/social_log": {
      "post": {
        "summary": "Insert a social log entry",
        "operationId": "insertSocialLog",
        "security": [{"BearerAuth": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "privacy":  {"type": "boolean"},
                  "user":     {"type": "string", "maxLength": 40},
                  "type":     {"type": "string", "maxLength": 40},
                  "target":   {"type": "string", "maxLength": 40},
                  "email":    {"type": "string", "maxLength": 80},
                  "text":     {"type": "string"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Entry inserted successfully",
            "content": {
              "application/json": {
                "schema": {"type": "object", "properties": {"id": {"type": "integer"}}}
              }
            }
          },
          "401": {
            "description": "Missing or invalid token, or insufficient permissions (bit 1 required)",
            "content": {
              "application/json": {
                "schema": {"type": "object", "properties": {"error": {"type": "string"}}}
              }
            }
          }
        }
      },
      "get": {
        "summary": "Query social log entries",
        "operationId": "getSocialLog",
        "security": [{"BearerAuth": []}],
        "parameters": [
          {"name": "from_id", "in": "query", "schema": {"type": "integer", "default": 0}, "description": "Return only entries with id >= from_id. If 0 or omitted, returns the last entries up to limit."},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 100}, "description": "Maximum number of entries to return"},
          {"name": "order", "in": "query", "schema": {"type": "string", "enum": ["desc", "asc"], "default": "desc"}, "description": "Sort order by id"}
        ],
        "responses": {
          "200": {
            "description": "Array of social log entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id":       {"type": "integer"},
                      "privacy":  {"type": "boolean"},
                      "user":     {"type": "string"},
                      "type":     {"type": "string"},
                      "target":   {"type": "string"},
                      "email":    {"type": "string"},
                      "text":     {"type": "string"},
                      "time":     {"type": "string", "format": "date-time"}
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token, or insufficient permissions",
            "content": {
              "application/json": {
                "schema": {"type": "object", "properties": {"error": {"type": "string"}}}
              }
            }
          }
        }
      }
    }
  }
}