🚀 Winget-Repo REST API Documentation

1. Overview

This document provides a complete overview of all available REST API endpoints for the Winget-Repo service.

📑 Documentation

1. Login to Winget-Repo
2. Click the REST-API Symbol in the Tools section

2. Authentication Mechanisms

2.1 Administrator Authentication (Bearer)

• Usage: Required for modifying data (Add/Edit/Delete packages).
• Verification: HTTPBearer - Bearer Token without usage has a 1 hour lifetime

2.2 Client Authentication (Auth-Token)

• Usage: Used by the Winget Client to fetch packages.
• Logic: If CLIENT_AUTHENTICATION is enabled in settings, the API verifies the auth_token. It also checks if the specific client IP/Token combination is blacklisted.

3. Endpoint Reference

3.1 Authentication & Session

POST /client/api/login

Authenticates a dashboard user and creates a rest session.

• Tags: Authentication
• Content-Type: application/x-www-form-urlencoded
• Parameters:
  • username (Form, str, required)
  • password (Form, str, required)
• Responses:
  • 200 OK: {"message": "<session_token_string>"}
  • 401 Unauthorized: Invalid credentials.

POST /client/api/logout

Invalidates a specific session token.

• Tags: Authentication
• Parameters:
  • token (Form, str, required): The session token to destroy.
• Responses:
  • 200 OK: {"message": "Logout Successful!"}

GET /client/api/test

Simple heartbeat to verify Bearer token validity.

• Tags: Authentication
• Headers:
  • Authorization: Bearer <token>
• Responses:
  • 200 OK: {"Message": "Its working!"}

3.2 Client Operations

POST /client/api/client_version

Retrieves the latest version of the Winget-Repo Client executable.

• Tags: Winget-Repo Client
• Security Logic:
  1. Checks Bearer token (Admin access).
  2. If failing, checks auth_token (Client access) if authentication is enforced settings.
• Parameters:
  • auth_token (Form, str, optional): Client specific token.
  • client (Form, int, optional): Client ID (default 0).
• Responses:
  • 200 OK: {"Version": "2.5.0.0"}
  • 401 Unauthorized: If authentication is enabled and fails.

POST /client/api/get_packages

Retrieves the full catalog of packages.

• Tags: Packages
• Description: Returns packages, available versions, and Base64 encoded logos. Applies "Blacklist" filtering if accessed via Client Auth-Token.
• Parameters:
  • include_disabled (Query, bool, default False): If true, returns inactive packages.
  • auth_token (Form, str, optional).
  • client (Form, int, optional).
• Responses:
  • 200 OK: JSON Array of Package Object.

3.3 Package Management (Admin Only)

Requires: Authorization: Bearer <token>

POST /client/api/add_package

Creates a new package entry in the database.

• Tags: Packages
• Parameters:
  • package_id (Form, str): Unique identifier (e.g., Mozilla.Firefox).
  • package_name (Form, str)
  • package_publisher (Form, str)
  • package_description (Form, str)
  • Logo (File, UploadFile, optional): PNG/JPG file.
• Responses:
  • 200 OK: {"Message": "Package was added successfully!"}
  • 401: Package ID already exists or creation failed.

PATCH /client/api/edit_package/{package_id}

Modifies an existing package's metadata or logo.

• Tags: Packages
• Path Parameters:
  • package_id: The ID of the package to edit.
• Form Parameters:
  • package_name, package_publisher, package_description
  • Logo (File, Optional)
• Responses:
  • 200 OK: {"Message": "Package was updated successfully!"}
  • 404: Package not found.

DELETE /client/api/delete_package/{package_id}

Deletes a package and all associated versions and files.

• Tags: Packages
• Responses:
  • 200 OK: {"Message": "Package was deleted successfully!"}

3.4 Package Version Control

GET /client/api/get_package_versions/{package_id}

Retrieves all versions associated with a package ID.

• Tags: Package Versions
• Responses:
  • 200 OK: Array of Package_Version Object. Includes nested installer paths if applicable.

GET /client/api/get_specific_package_version/{version_uid}

Retrieves details for a single version using its unique UUID.

• Tags: Package Versions
• Responses:
  • 200 OK: Single Package_Version Object.

DELETE /client/api/delete_package_version/{package_id}

Deletes specific versions of a package.

• Tags: Package Versions
• Parameters:
  • versions_uids (Form, List[str]): A list of UUIDs or a comma-separated string of UUIDs.
• Responses:
  • 200 OK: {"Message": "Package versions deleted successfully!"}

3.5 Add Package Version

POST /client/api/add_package_version/{package_id}

Create a new package version

• Tags: Package Versions
• Parameters:
  • file (file): Upload the installer file
  • Metadata (Form):
    • package_version: (e.g., "1.0.0")
    • file_architect: Enum Architecture
    • file_type: Enum FileType
    • file_scope: Enum Scope
    • package_locale: Enum Locale
    • channel: (Default: "stable")
  • Switches (Optional Form):
    • switch_Silent, switch_Interactive, switch_Log, switch_Upgrade, switch_Custom, switch_Repair
  • Advanced (Optional Form):
    • productcode, upgradecode, package_family_name, file_type_nested, file_nested_path
• Responses:
  • 201 Created: {"Message": "...", "UID": "<new_version_uid>"}
  • 409 Conflict: Version already exists.
  • 407: Storage quota exceeded.

3.6 Client Management

Requires: Authorization: Bearer <token>

GET /client/api/get_clients

Retrieves a list of all registered clients.

• Tags: Clients
• Responses:
  • 200 OK: JSON Array of client objects containing full metadata.

POST /client/api/add_client

Adds a new client and returns its generated auth token.

• Tags: Clients
• Parameters:
  • client_name (Form, str, required): The hostname of the client to add.
• Responses:
  • 201 Created: {"Message": "Client was added successfully!", "client_id": "<uuid>", "auth_token": "<uuid>"}
  • 400 Bad Request: No client name provided, or IP could not be resolved from hostname.
  • 409 Conflict: Hostname already exists.

DELETE /client/api/delete_client/{client_id}/{auth_token}

Deletes an existing client by its ID and auth token.

• Tags: Clients
• Path Parameters:
  • client_id: The unique UUID of the client to delete.
  • auth_token: The auth token of the client to delete.
• Responses:
  • 200 OK: {"Message": "Client was removed successfully!"}
  • 400 Bad Request: Missing client ID or auth token.
  • 404 Not Found: Client does not exist.

4. Response Models

4.1 Package Object

{
  "PACKAGE_ID": "string",
  "PACKAGE_NAME": "string",
  "PACKAGE_PUBLISHER": "string",
  "PACKAGE_DESCRIPTION": "string",
  "PACKAGE_LOGO": "data:image/png;base64,.....",
  "PACKAGE_ACTIVE": "string (1 or 0)",
  "VERSIONS": ["1.2.0", "1.1.0"],
  "VERSIONS_UID": ["uuid-string-1", "uuid-string-2"]
}

4.2 Package_Version Object (Response)

{
  "PACKAGE_ID": "Google.Chrome",
  "VERSION": "120.0.1",
  "LOCALE": "en-US",
  "ARCHITECTURE": "x64",
  "INSTALLER_TYPE": "MSI",
  "INSTALLER_URL": "Download_Url",
  "INSTALLER_SHA256": "e3b0c44298fc1c149afbf4c8996fb...",
  "INSTALLER_SCOPE": "machine",
  "UID": "a1b2c3d4-e5f6...",
  "INSTALLER_NESTED_TYPE": "EXE",
  "PRODUCTCODE": "{GUID}",
  "UPGRADECODE": "{GUID}",
  "PACKAGE_FAMILY_NAME": "Chrome_Package",
  "CHANNEL": "stable",
  "NESTED_PACKAGE_INSTALLER_PATHS": []
}

5. Enums & Constants

5.1 Detailed Enums

• Architecture: x64, x86, arm, arm64
• FileType: EXE, MSI, MSIX, APPX, ZIP, INNO, NULLSOFT, WIX, BURN
• Scope: machine, user
• Locale: en-US, de-DE, de-AT, de-CH, en-GB, en-CA, en-AU, fr-FR, fr-CA, fr-BE, es-ES, es-MX, it-IT, it-CH, pt-PT, pt-BR, ja-JP, ko_KR, zh_CN, zh_TW

6. Error Codes Summary