{
  "components": {
    "parameters": {
      "projectRef": {
        "description": "Project UUID or live slug, or an unexpired slug alias. Expired aliases return 404 PROJECT_NOT_FOUND. POST does not 301.",
        "in": "path",
        "name": "project_ref",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Admin": {
        "description": "System instance administrator account entity.",
        "properties": {
          "created_at": {
            "description": "Account creation timestamp.",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Unique administrator UUID.",
            "format": "uuid",
            "type": "string"
          },
          "is_platform_admin": {
            "description": "True for platform superusers. Project-only members are false.",
            "type": "boolean"
          },
          "last_login_at": {
            "description": "UTC timestamp of the most recent successful HTTP login, or null if the account has never signed in.",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "last_login_ip": {
            "description": "Client IP of the most recent successful HTTP login, or null if unknown or never signed in.",
            "nullable": true,
            "type": "string"
          },
          "updated_at": {
            "description": "Account last updated timestamp.",
            "format": "date-time",
            "type": "string"
          },
          "username": {
            "description": "Administrator login username.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "Admin2FAStatusOutput": {
        "properties": {
          "passkeys": {
            "items": {
              "$ref": "#/components/schemas/AdminPasskey"
            },
            "type": "array"
          },
          "recovery_remaining": {
            "type": "integer"
          },
          "totp_enabled": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "Admin2FAVerifyInput": {
        "properties": {
          "recovery_code": {
            "description": "One unused recovery code.",
            "type": "string"
          },
          "totp": {
            "description": "TOTP code for second factor.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AdminAnnouncement": {
        "description": "Admin-plane announcement including drafts and scope fields. List and reorder omit content; GET, POST, and PATCH include the markdown body.",
        "properties": {
          "arch": {
            "nullable": true,
            "type": "string"
          },
          "content": {
            "description": "Markdown body. Omitted on list and reorder responses.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "ends_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "language": {
            "description": "Language code for this row (one language per announcement).",
            "type": "string"
          },
          "os": {
            "nullable": true,
            "type": "string"
          },
          "sort_order": {
            "type": "integer"
          },
          "starts_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "status": {
            "enum": [
              "draft",
              "scheduled",
              "published"
            ],
            "type": "string"
          },
          "subtitle": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "version_id": {
            "description": "Bound Version UUID; null when not version-scoped. No foreign key.",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "AdminListOutput": {
        "description": "List of instance administrator accounts.",
        "properties": {
          "admins": {
            "description": "List of registered administrator profiles.",
            "items": {
              "$ref": "#/components/schemas/Admin"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "AdminLoginInput": {
        "description": "Credentials required for instance administrator login.",
        "properties": {
          "password": {
            "description": "Administrator account password.",
            "format": "password",
            "type": "string"
          },
          "username": {
            "description": "Administrator login username.",
            "type": "string"
          }
        },
        "required": [
          "username",
          "password"
        ],
        "type": "object"
      },
      "AdminLoginOutput": {
        "description": "Password login or 2FA step result. status=pending returns pending_token and stage; status=complete returns access_token and admin.",
        "properties": {
          "access_token": {
            "description": "Opaque session token present when status=complete.",
            "type": "string"
          },
          "admin": {
            "$ref": "#/components/schemas/Admin",
            "description": "Administrator profile. Present on complete login."
          },
          "expires_in": {
            "description": "Token validity duration in seconds. Full sessions use idle TTL; pending tokens use login_pending_ttl_seconds.",
            "type": "integer"
          },
          "has_passkey": {
            "description": "true when the pending account has at least one registered passkey; only present when status=pending and stage=second_factor.",
            "type": "boolean"
          },
          "otpauth_url": {
            "description": "otpauth:// URL for authenticator enrollment.",
            "type": "string"
          },
          "pending_token": {
            "description": "Short-lived restricted token present when status=pending.",
            "type": "string"
          },
          "recovery_codes": {
            "description": "Plaintext recovery codes, returned once after TOTP confirm or regenerate.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "secret": {
            "description": "TOTP base32 secret during setup. Never logged or cached.",
            "type": "string"
          },
          "stage": {
            "description": "Pending login stage.",
            "enum": [
              "enroll_totp",
              "ack_recovery",
              "optional_passkey",
              "second_factor"
            ],
            "type": "string"
          },
          "status": {
            "description": "pending requires additional 2FA or enrollment steps; complete is a full session.",
            "enum": [
              "pending",
              "complete"
            ],
            "type": "string"
          },
          "token_type": {
            "description": "Authentication token scheme.",
            "example": "Bearer",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AdminPasskey": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AdminPasskeyListOutput": {
        "properties": {
          "passkeys": {
            "items": {
              "$ref": "#/components/schemas/AdminPasskey"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "AdminPatchInput": {
        "description": "Partial administrator update. Empty or omitted password means no password change.",
        "properties": {
          "password": {
            "description": "New password; omit or empty to leave unchanged.",
            "format": "password",
            "type": "string"
          },
          "username": {
            "description": "New username; omit or empty to leave unchanged.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AdminRecoveryAckInput": {
        "properties": {
          "confirmed": {
            "description": "Must be true to acknowledge recovery codes were saved.",
            "type": "boolean"
          }
        },
        "required": [
          "confirmed"
        ],
        "type": "object"
      },
      "AdminRecoveryCodesOutput": {
        "properties": {
          "recovery_codes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "AdminTOTPCodeInput": {
        "properties": {
          "code": {
            "description": "Current 6-digit TOTP code.",
            "type": "string"
          }
        },
        "required": [
          "code"
        ],
        "type": "object"
      },
      "AdminTOTPSetupOutput": {
        "properties": {
          "otpauth_url": {
            "type": "string"
          },
          "secret": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AdminWebAuthnFinishInput": {
        "properties": {
          "credential": {
            "description": "WebAuthn attestation or assertion JSON from the authenticator."
          },
          "name": {
            "description": "Display name for a newly registered passkey.",
            "type": "string"
          }
        },
        "required": [
          "credential"
        ],
        "type": "object"
      },
      "AdminWebAuthnOptionsOutput": {
        "properties": {
          "options": {
            "description": "PublicKeyCredentialCreationOptions or RequestOptions from the WebAuthn ceremony."
          }
        },
        "type": "object"
      },
      "AdminWriteInput": {
        "description": "Username and password for creating an administrator account. Both fields required on POST.",
        "properties": {
          "password": {
            "description": "Password string (minimum 8 characters).",
            "format": "password",
            "type": "string"
          },
          "username": {
            "description": "Alphanumeric administrator username.",
            "type": "string"
          }
        },
        "required": [
          "username",
          "password"
        ],
        "type": "object"
      },
      "Artifact": {
        "description": "Downloadable file or package binary associated with a specific platform version line.",
        "properties": {
          "artifact_signature": {
            "description": "Detached cryptographic signature over the file bytes.",
            "nullable": true,
            "type": "string"
          },
          "compatible_hw_revs": {
            "description": "List of explicitly compatible hardware revisions.",
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "content_type": {
            "description": "MIME media type for HTTP Content-Type header.",
            "type": "string"
          },
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "file_name": {
            "description": "Stable download file name.",
            "type": "string"
          },
          "hw_rev": {
            "description": "Hardware revision slug if variant-specific.",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "description": "Unique artifact identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "kind": {
            "description": "Artifact category: full (hash-root native), store_full (path zip for stores), delta, patch, file.",
            "enum": [
              "full",
              "store_full",
              "delta",
              "patch",
              "file"
            ],
            "type": "string"
          },
          "fileset_sha256": {
            "description": "Canonical fileset hash (patch artifacts only).",
            "type": "string"
          },
          "compression": {
            "description": "Archive compression format (zip for full/store_full/patch).",
            "type": "string"
          },
          "max_hw_rev": {
            "description": "Maximum compatible hardware revision.",
            "nullable": true,
            "type": "string"
          },
          "md5": {
            "description": "Hex-encoded MD5 checksum.",
            "type": "string"
          },
          "min_hw_rev": {
            "description": "Minimum compatible hardware revision.",
            "nullable": true,
            "type": "string"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "sha256": {
            "description": "Hex-encoded SHA-256 checksum.",
            "type": "string"
          },
          "sha512": {
            "description": "Hex-encoded SHA-512 checksum.",
            "nullable": true,
            "type": "string"
          },
          "size": {
            "description": "File size in bytes.",
            "type": "integer"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "version_id": {
            "description": "ID of the associated Version.",
            "format": "uuid",
            "type": "string"
          },
          "version_line_id": {
            "description": "ID of the associated Version Line.",
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AuditListOutput": {
        "description": "Paginated list of administrative audit events.",
        "properties": {
          "events": {
            "description": "Audit events newest-first.",
            "items": {
              "properties": {
                "action": {
                  "description": "Action performed (e.g. version.publish).",
                  "type": "string"
                },
                "actor_fingerprint": {
                  "description": "Username or token fingerprint (never a plaintext token).",
                  "type": "string"
                },
                "actor_id": {
                  "description": "Actor UUID when known.",
                  "format": "uuid",
                  "type": "string"
                },
                "actor_type": {
                  "description": "Actor type: admin, project_token, or ci_token.",
                  "type": "string"
                },
                "created_at": {
                  "description": "Timestamp of the action.",
                  "format": "date-time",
                  "type": "string"
                },
                "detail": {
                  "additionalProperties": true,
                  "description": "Structured details of the modification (jsonb).",
                  "type": "object"
                },
                "id": {
                  "description": "Audit event UUID.",
                  "format": "uuid",
                  "type": "string"
                },
                "project_id": {
                  "description": "Owning project UUID when the event is project-scoped.",
                  "format": "uuid",
                  "type": "string"
                },
                "resource_id": {
                  "description": "Target resource identifier.",
                  "type": "string"
                },
                "resource_type": {
                  "description": "Target resource type.",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Cursor token for the next page; empty when no more events.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AutoPublishRule": {
        "description": "Gating rule for publishing when required platform lines are ready (required_lines like windows/x86_64).",
        "properties": {
          "allow_partial": {
            "description": "When true, publish even if some required lines are missing (default false).",
            "type": "boolean"
          },
          "required_lines": {
            "description": "Platform lines such as windows/x86_64.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "BuildInfo": {
        "additionalProperties": false,
        "description": "Build identity of this process. version/commit/build_time come from linker injection in the release toolchain; a binary built without injection reports dev and unknown instead of failing.",
        "properties": {
          "build_time": {
            "description": "Build timestamp in RFC 3339 UTC as injected by the release toolchain. \"unknown\" when nothing was injected: the process never guesses a compile time from its own start time.",
            "example": "2026-09-21T03:15:02Z",
            "type": "string"
          },
          "cgo_enabled": {
            "description": "True when this binary links C/C++ code (the official server build always does). Comes from the build constraint, not from injection.",
            "type": "boolean"
          },
          "commit": {
            "description": "Source revision this binary was built from: short SHA, with a -dirty suffix when the worktree was modified. \"unknown\" when neither injection nor VCS stamping supplied it.",
            "example": "4f2a1c9",
            "type": "string"
          },
          "go_version": {
            "description": "Go toolchain version running this process (runtime fact, never injected).",
            "example": "go1.27.0",
            "type": "string"
          },
          "platform": {
            "description": "Build target as goos/goarch (runtime fact, never injected).",
            "example": "windows/amd64",
            "type": "string"
          },
          "version": {
            "description": "Release version without a v prefix. \"dev\" for anything the release toolchain did not build, so an operator can tell a local binary from an official one.",
            "example": "0.1.0",
            "type": "string"
          }
        },
        "required": [
          "build_time",
          "cgo_enabled",
          "commit",
          "go_version",
          "platform",
          "version"
        ],
        "type": "object"
      },
      "CIReleasesOutput": {
        "description": "Response returned when an automated CI release bundle is accepted for background processing.",
        "properties": {
          "job_id": {
            "description": "UUID of the asynchronous bundle unpacking job.",
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "description": "Initial state of the background job.",
            "example": "queued",
            "type": "string"
          }
        },
        "type": "object"
      },
      "CIToken": {
        "description": "Restricted continuous integration token used by CI/CD runners to publish releases.",
        "properties": {
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "description": "Expiration timestamp (UTC ISO-8601).",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "fingerprint": {
            "description": "SHA-256 fingerprint of the token used for audit and per-token rate limiting.",
            "type": "string"
          },
          "id": {
            "description": "Unique CI token identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "name": {
            "description": "Label identifying the CI pipeline or runner.",
            "type": "string"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "scopes": {
            "description": "Granted scopes restricted to automated CI workflows.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "token": {
            "description": "Plaintext kvc_… shown only on create",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ChangelogEntry": {
        "description": "Release changelog content including title and Markdown text for a specific locale.",
        "properties": {
          "markdown": {
            "description": "Markdown text describing release changes.",
            "type": "string"
          },
          "title": {
            "description": "Release version heading.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ChangelogMap": {
        "additionalProperties": {
          "$ref": "#/components/schemas/ChangelogEntry"
        },
        "description": "Locale-keyed changelog map (e.g. zh-CN, en) of ChangelogEntry values.",
        "type": "object"
      },
      "Channel": {
        "description": "Distribution channel representing a stability track (e.g. stable, beta, alpha, lts).",
        "properties": {
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "enabled": {
            "description": "Whether new versions can be published to this channel.",
            "type": "boolean"
          },
          "id": {
            "description": "Unique channel identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "name": {
            "description": "Required display name. Seeded at project create from system_channel_names or English slugs.",
            "type": "string"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "slug": {
            "description": "Custom slugs match ^[a-z0-9-]{3,64}$; underscore is rejected. lts is allowed and does not set Version is_lts.",
            "type": "string"
          },
          "stability_rank": {
            "description": "System defaults: alpha=10, beta=20, stable=30",
            "type": "integer"
          },
          "system": {
            "description": "System names cannot be deleted",
            "type": "boolean"
          },
          "token": {
            "description": "Plaintext channel token. Empty when unset or when only a legacy hash exists.",
            "type": "string"
          },
          "token_required": {
            "description": "True when a channel token hash is stored.",
            "type": "boolean"
          },
          "unlisted": {
            "description": "Hidden from public catalog and not an auto-upgrade target unless the client is already on this channel or query channel matches.",
            "type": "boolean"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "CleanupOutput": {
        "description": "Result of artifact retention cleanup.",
        "properties": {
          "cleaned_count": {
            "description": "Number of expired or abandoned upload sessions and unreferenced artifacts removed.",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Client": {
        "description": "Project client registry row. device_hash follows device_id_policy; raw device_id is never returned.",
        "properties": {
          "country_code": {
            "description": "ISO country code from fused GeoIP; empty when unknown.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "custom": {
            "additionalProperties": true,
            "type": "object"
          },
          "device_hash": {
            "type": "string"
          },
          "geo_i18n": {
            "$ref": "#/components/schemas/GeoI18n"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "last_arch": {
            "type": "string"
          },
          "last_channel": {
            "type": "string"
          },
          "last_check_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "last_ip": {
            "type": "string"
          },
          "last_os": {
            "type": "string"
          },
          "last_version": {
            "type": "string"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          },
          "region_code": {
            "description": "ISO region/subdivision code; empty when unknown.",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ClientBuckets": {
        "properties": {
          "active_24h": {
            "type": "integer"
          },
          "active_7d": {
            "type": "integer"
          },
          "arch": {
            "items": {
              "$ref": "#/components/schemas/NameCount"
            },
            "type": "array"
          },
          "channels": {
            "items": {
              "$ref": "#/components/schemas/NameCount"
            },
            "type": "array"
          },
          "countries": {
            "items": {
              "$ref": "#/components/schemas/CountryCount"
            },
            "type": "array"
          },
          "os": {
            "items": {
              "$ref": "#/components/schemas/NameCount"
            },
            "type": "array"
          },
          "recency_hours": {
            "items": {
              "$ref": "#/components/schemas/NameCount"
            },
            "type": "array"
          },
          "total": {
            "type": "integer"
          },
          "versions": {
            "items": {
              "$ref": "#/components/schemas/NameCount"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ClientDailyPoint": {
        "properties": {
          "active_count": {
            "type": "integer"
          },
          "day": {
            "format": "date",
            "type": "string"
          },
          "failed_count": {
            "description": "Telemetry failed events on this UTC day.",
            "type": "integer"
          },
          "installed_count": {
            "description": "Telemetry installed events on this UTC day.",
            "type": "integer"
          },
          "new_count": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ClientDailySeriesOutput": {
        "properties": {
          "series": {
            "items": {
              "$ref": "#/components/schemas/ClientDailyPoint"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ClientListOutput": {
        "properties": {
          "clients": {
            "items": {
              "$ref": "#/components/schemas/Client"
            },
            "type": "array"
          },
          "total": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "CountryCount": {
        "properties": {
          "code": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "names": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Fused country names for this code.",
            "type": "object"
          }
        },
        "type": "object"
      },
      "DeleteTelemetryOutput": {
        "description": "Result of privacy data erasure for a device identifier.",
        "properties": {
          "allowlist_deleted": {
            "description": "Count of gray allowlist entries erased.",
            "type": "integer"
          },
          "telemetry_deleted": {
            "description": "Count of telemetry records erased.",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Error": {
        "description": "Standard unified error envelope format: { error: { code, message, details } }.",
        "properties": {
          "error": {
            "description": "Nested error object.",
            "properties": {
              "code": {
                "enum": [
                  "PROJECT_NOT_FOUND",
                  "VERSION_NOT_FOUND",
                  "VERSION_LINE_NOT_FOUND",
                  "VERSION_NOT_VISIBLE",
                  "VERSION_REVOKED",
                  "NO_SAFE_TARGET",
                  "INTERMEDIATE_UNAVAILABLE",
                  "ARTIFACT_REQUIRED",
                  "CHANNEL_SUFFIX_MISMATCH",
                  "VERSION_ALREADY_EXISTS",
                  "GRAY_NOT_ALLOWED_ON_CRITICAL",
                  "PACKAGE_TYPE_IMMUTABLE",
                  "ENGINE_MISMATCH",
                  "COMPARE_ENGINE_IMMUTABLE",
                  "INVALID_PATH",
                  "ARTIFACT_IMMUTABLE",
                  "UNAUTHORIZED",
                  "FORBIDDEN",
                  "PRECONDITION_FAILED",
                  "HW_REV_UNKNOWN",
                  "HW_REV_INCOMPATIBLE",
                  "DELTA_ALGO_UNSUPPORTED",
                  "MIN_OS_NOT_MET",
                  "RATE_LIMITED",
                  "TOTP_RATE_LIMITED",
                  "CHANGELOG_QUERY_INVALID",
                  "UPLOAD_INCOMPLETE",
                  "CHANNEL_NOT_FOUND",
                  "CHANNEL_CONFLICT",
                  "CHECKSUM_MISMATCH",
                  "JOB_NOT_FOUND",
                  "JOB_FAILED",
                  "AUTO_PUBLISH_PENDING",
                  "ZIP_LAYOUT_INVALID",
                  "ADMIN_NOT_FOUND",
                  "USERNAME_TAKEN",
                  "LAST_ADMIN",
                  "LAST_OWNER",
                  "MEMBER_NOT_FOUND",
                  "CLIENT_NOT_FOUND",
                  "GEOIP_NOT_FOUND",
                  "LANGUAGE_TAKEN",
                  "LANGUAGE_NOT_FOUND",
                  "NOT_READY",
                  "INTERNAL_ERROR",
                  "INVALID_REQUEST",
                  "INVALID_QUERY_PARAM"
                ],
                "type": "string"
              },
              "details": {},
              "message": {
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "GeoI18n": {
        "description": "Fused locale maps for country and region names. No single-language country_name.",
        "properties": {
          "country": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "region": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "GeoipDatabase": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "file_name": {
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "rank": {
            "type": "integer"
          },
          "size": {
            "format": "int64",
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "GeoipListOutput": {
        "properties": {
          "databases": {
            "items": {
              "$ref": "#/components/schemas/GeoipDatabase"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "GeoipPatchInput": {
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "rank": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ClusterNode": {
        "description": "A process identity row on shared Postgres. Heartbeat is local UPDATE, not HTTP.",
        "properties": {
          "admin_enabled": {
            "type": "boolean"
          },
          "cpu_percent": {
            "type": "number"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "is_current": {
            "description": "True when this row is the admin process serving this request.",
            "type": "boolean"
          },
          "last_seen_at": {
            "format": "date-time",
            "type": "string"
          },
          "mem_total_bytes": {
            "format": "int64",
            "type": "integer"
          },
          "mem_used_bytes": {
            "format": "int64",
            "type": "integer"
          },
          "offline": {
            "type": "boolean"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "type": "object"
      },
      "ClusterNodeListOutput": {
        "additionalProperties": false,
        "properties": {
          "cluster_active": {
            "description": "True when this process is in cluster mode (storage.driver=s3 and cache.driver=redis). Independent of node row count.",
            "type": "boolean"
          },
          "nodes": {
            "items": {
              "$ref": "#/components/schemas/ClusterNode"
            },
            "type": "array"
          }
        },
        "required": [
          "cluster_active",
          "nodes"
        ],
        "type": "object"
      },
      "NodeArtifactSync": {
        "description": "Per-node replica progress for a version line.",
        "properties": {
          "bytes_done": {
            "format": "int64",
            "type": "integer"
          },
          "bytes_total": {
            "format": "int64",
            "type": "integer"
          },
          "display_name": {
            "type": "string"
          },
          "error_message": {
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "line_id": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "node_id": {
            "format": "uuid",
            "type": "string"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "enum": [
              "syncing",
              "ready",
              "error"
            ],
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "version_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "type": "object"
      },
      "NodeArtifactSyncListOutput": {
        "properties": {
          "sync": {
            "items": {
              "$ref": "#/components/schemas/NodeArtifactSync"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "GrayAllowlistDeleteOutput": {
        "description": "Result of removing device identifiers from the gray rollout allowlist.",
        "properties": {
          "entries": {
            "description": "Array of removed allowlist records.",
            "items": {
              "$ref": "#/components/schemas/GrayAllowlistEntry"
            },
            "type": "array"
          },
          "removed": {
            "description": "Count of allowlist entries deleted.",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "GrayAllowlistEntry": {
        "description": "Gray allowlist entry. device_id is the stored form: HMAC hex under the hashed policy, raw value under the raw policy. Plaintext is never echoed.",
        "properties": {
          "created_at": {
            "description": "Timestamp when the device was added to allowlist.",
            "format": "date-time",
            "type": "string"
          },
          "device_id": {
            "description": "Hashed device identifier stored securely.",
            "type": "string"
          },
          "source": {
            "description": "auto = incremental gray admission; manual = operator selected the device from the registry.",
            "enum": [
              "auto",
              "manual"
            ],
            "type": "string"
          },
          "id": {
            "description": "Unique allowlist entry identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "version_id": {
            "description": "Target version UUID.",
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "GrayAllowlistList": {
        "description": "List of device identifiers explicitly enrolled in the gray rollout allowlist.",
        "properties": {
          "entries": {
            "description": "Array of allowlist device records.",
            "items": {
              "$ref": "#/components/schemas/GrayAllowlistEntry"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "GrayAllowlistWriteInput": {
        "description": "client_ids are namebook UUIDs (not raw device_id). Policy none is rejected with 400.",
        "properties": {
          "client_ids": {
            "description": "Registered client UUIDs to add or remove from the version allowlist.",
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "client_ids"
        ],
        "type": "object"
      },
      "GrayClientRow": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Client"
          },
          {
            "properties": {
              "source": {
                "enum": [
                  "auto",
                  "manual"
                ],
                "type": "string"
              },
              "updated": {
                "description": "last_version compare key >= this version.",
                "type": "boolean"
              }
            },
            "type": "object"
          }
        ],
        "type": "object"
      },
      "GrayClientsOutput": {
        "properties": {
          "clients": {
            "items": {
              "$ref": "#/components/schemas/GrayClientRow"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "GrayPatchInput": {
        "description": "Patch incremental gray knobs. Does not reset gray_started_at.",
        "properties": {
          "gray_interval_seconds": {
            "description": "Seconds between coverage ticks. k = floor(elapsed / interval).",
            "minimum": 1,
            "type": "integer"
          },
          "gray_start_percent": {
            "description": "Starting gray coverage percent at t=0. 100 (default) publishes as full push.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "gray_step_percent": {
            "description": "Coverage percent added after each interval tick.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "GraySeriesOutput": {
        "properties": {
          "series": {
            "items": {
              "$ref": "#/components/schemas/GraySeriesPoint"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "GraySeriesPoint": {
        "properties": {
          "allowlisted": {
            "type": "integer"
          },
          "desired": {
            "type": "integer"
          },
          "n": {
            "type": "integer"
          },
          "taken_at": {
            "format": "date-time",
            "type": "string"
          },
          "target_percent": {
            "type": "integer"
          },
          "updated": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "GrayStatus": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Version"
          },
          {
            "properties": {
              "actual_percent": {
                "type": "integer"
              },
              "allowlisted": {
                "type": "integer"
              },
              "completed": {
                "type": "boolean"
              },
              "desired": {
                "type": "integer"
              },
              "n": {
                "type": "integer"
              },
              "target_percent": {
                "type": "integer"
              },
              "updated": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        ],
        "description": "Version JSON plus incremental gray KPIs.",
        "type": "object"
      },
      "HwRev": {
        "description": "Hardware revision definition defining an ordered hardware generation for an embedded or physical device.",
        "properties": {
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Unique hardware revision identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "notes": {
            "description": "Optional release notes or description for this hardware revision.",
            "type": "string"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "rank": {
            "description": "Integer rank establishing the hardware revision timeline ordering.",
            "type": "integer"
          },
          "slug": {
            "description": "Hardware generation slug. After normalize must match ^[a-z0-9_-]{1,64}$ (v1 allowed; independent of OS/Arch min-3).",
            "type": "string"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "Job": {
        "description": "Asynchronous background task (e.g. bundle unpacking, delta generation, archive packaging).",
        "properties": {
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "error_message": {
            "description": "Detailed error message if the job failed.",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "description": "Unique background task identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "job_id": {
            "description": "Unique identifier (UUID v4) of the background job.",
            "format": "uuid",
            "type": "string"
          },
          "progress": {
            "description": "Optional progress indication (0-100).",
            "type": "integer"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "result": {
            "description": "Structured output upon successful job completion."
          },
          "status": {
            "description": "Job execution status: 'queued', 'running', 'succeeded', 'failed'.",
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ],
            "type": "string"
          },
          "type": {
            "description": "Job type: 'bundle_unpack', 'delta_generate', 'auto_delta', 'webhook_deliver'.",
            "type": "string"
          },
          "updated_at": {
            "description": "Last status update timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LineDefaultsOutput": {
        "description": "Prefill values from the highest compare-key version strictly below the current version that has the requested line. Nulls if none.",
        "properties": {
          "min_api_level": {
            "nullable": true,
            "type": "integer"
          },
          "min_os": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "LineRolloutPatchInput": {
        "description": "min_os / min_api_level omit=keep, null=clear, value=write.",
        "properties": {
          "min_api_level": {
            "minimum": 0,
            "nullable": true,
            "type": "integer"
          },
          "min_os": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ManifestEntry": {
        "description": "Single file record in a multi-file version line manifest.",
        "properties": {
          "install_policy": {
            "description": "Installation behavior: 'OVERWRITE' or 'KEEP_IF_EXISTS'.",
            "enum": [
              "OVERWRITE",
              "KEEP_IF_EXISTS"
            ],
            "type": "string"
          },
          "integrity_check": {
            "description": "Whether client integrity verification should validate this file.",
            "type": "boolean"
          },
          "md5": {
            "description": "Hex-encoded MD5 checksum of the file.",
            "type": "string"
          },
          "path": {
            "description": "Normalized relative file path (forward slashes, Unicode NFC).",
            "type": "string"
          },
          "sha256": {
            "description": "Hex-encoded SHA-256 checksum of the file.",
            "type": "string"
          },
          "size": {
            "description": "File size in bytes.",
            "type": "integer"
          }
        },
        "required": [
          "path",
          "size",
          "sha256",
          "md5"
        ],
        "type": "object"
      },
      "ManifestResult": {
        "description": "Multi-file manifest summary with calculated root hash and entry count.",
        "properties": {
          "count": {
            "description": "Total number of files in the manifest.",
            "type": "integer"
          },
          "entries": {
            "description": "List of manifest file entries.",
            "items": {
              "$ref": "#/components/schemas/ManifestEntry"
            },
            "type": "array"
          },
          "root_hash": {
            "description": "Composite Merkle-like root hash computed over sorted normalized file entries.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "InstallPolicyEntry": {
        "description": "Path install policy in a project or channel template.",
        "properties": {
          "install_policy": {
            "description": "Installation behavior: OVERWRITE or KEEP_IF_EXISTS.",
            "enum": [
              "OVERWRITE",
              "KEEP_IF_EXISTS"
            ],
            "type": "string"
          },
          "path": {
            "description": "Normalized relative file path.",
            "type": "string"
          }
        },
        "required": [
          "path",
          "install_policy"
        ],
        "type": "object"
      },
      "InstallPolicyReferenceOutput": {
        "description": "Latest non-revoked version on the selected channel for the matrix pair, plus that line's Manifest entries.",
        "properties": {
          "entries": {
            "items": {
              "$ref": "#/components/schemas/ManifestEntry"
            },
            "type": "array"
          },
          "status": {
            "description": "Version status when version is set.",
            "nullable": true,
            "type": "string"
          },
          "version": {
            "description": "Display version of the latest non-revoked Version on the channel; null when the channel has none.",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "entries"
        ],
        "type": "object"
      },
      "InstallPolicyRulesInput": {
        "properties": {
          "entries": {
            "items": {
              "$ref": "#/components/schemas/InstallPolicyEntry"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "InstallPolicyRulesOutput": {
        "properties": {
          "effective": {
            "description": "D1 overlay (channel GET only).",
            "items": {
              "$ref": "#/components/schemas/InstallPolicyEntry"
            },
            "type": "array"
          },
          "entries": {
            "items": {
              "$ref": "#/components/schemas/InstallPolicyEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "entries"
        ],
        "type": "object"
      },
      "MediaUploadFile": {
        "description": "One uploaded Markdown media object with hashes.",
        "properties": {
          "content_type": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "md5": {
            "type": "string"
          },
          "sha256": {
            "type": "string"
          },
          "sha512": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          },
          "url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "MemberListOutput": {
        "properties": {
          "members": {
            "items": {
              "$ref": "#/components/schemas/ProjectMember"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "MemberPatchInput": {
        "properties": {
          "role": {
            "enum": [
              "owner",
              "admin"
            ],
            "type": "string"
          }
        },
        "required": [
          "role"
        ],
        "type": "object"
      },
      "MemberWriteInput": {
        "properties": {
          "password": {
            "description": "When set, creates is_platform_admin=false. Omit to attach an existing account.",
            "format": "password",
            "type": "string"
          },
          "role": {
            "enum": [
              "owner",
              "admin"
            ],
            "type": "string"
          },
          "username": {
            "type": "string"
          }
        },
        "required": [
          "username",
          "role"
        ],
        "type": "object"
      },
      "NameCount": {
        "properties": {
          "count": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlatformCatalogOutput": {
        "description": "Catalog of preset operating systems and CPU architectures with recognized aliases.",
        "properties": {
          "arch": {
            "description": "List of supported CPU architecture metadata entries.",
            "items": {
              "properties": {
                "aliases": {
                  "description": "Accepted alias names.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "slug": {
                  "description": "Canonical architecture slug (e.g. x86_64, arm64, x86).",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "os": {
            "description": "List of supported operating system metadata entries.",
            "items": {
              "properties": {
                "aliases": {
                  "description": "Accepted alias names.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "slug": {
                  "description": "Canonical operating system slug (e.g. windows, linux, macos, android).",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "PlatformMatrix": {
        "description": "Platform matrix row defining supported OS, CPU architecture, package type, and delta rules. Minimum OS/API live on VersionLine.",
        "properties": {
          "arch": {
            "description": "Stored canonical (amd64 → x86_64, aarch64 → arm64)",
            "type": "string"
          },
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "delta_algo": {
            "default": "hdiffpatch",
            "description": "Default binary delta algorithm ('hdiffpatch', 'bsdiff', 'xdelta3').",
            "enum": [
              "hdiffpatch",
              "bsdiff",
              "xdelta3"
            ],
            "type": "string"
          },
          "delta_source_count": {
            "default": 3,
            "description": "Number of recent historical versions to pre-generate delta patches against (default: 3).",
            "type": "integer"
          },
          "fallback_arch": {
            "description": "Empty means off",
            "type": "string"
          },
          "hw_variant_policy": {
            "default": "independent",
            "description": "Hardware revision compatibility policy: 'independent' or 'higher_compatible_with_lower'.",
            "enum": [
              "independent",
              "higher_compatible_with_lower"
            ],
            "type": "string"
          },
          "id": {
            "description": "Unique platform matrix entry identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "minimum_supported_version": {
            "description": "Null falls back to the project field",
            "nullable": true,
            "type": "string"
          },
          "os": {
            "description": "Stored canonical (darwin/osx → macos). ipados is stored as-is to enable a distinct matrix row.",
            "type": "string"
          },
          "package_type": {
            "description": "Package packaging mode ('single_file' or 'multi_file'). Immutable once published.",
            "enum": [
              "single_file",
              "multi_file"
            ],
            "type": "string"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "PresignUploadOutput": {
        "description": "API or TUS upload URL. Artifact bytes are never PUT to unknown S3 keys.",
        "properties": {
          "direct_s3": {
            "description": "Always false. Incoming artifacts write local temp then promote to {slug}/{sha256}.",
            "type": "boolean"
          },
          "method": {
            "description": "HTTP method to use (typically 'PUT').",
            "type": "string"
          },
          "upload_url": {
            "description": "Presigned HTTP PUT URL or API relay upload endpoint.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "Project": {
        "additionalProperties": false,
        "description": "Core project domain entity providing tenant isolation, security, storage, and update policies.",
        "properties": {
          "cache_s_maxage_seconds": {
            "default": 60,
            "description": "CDN shared-cache s-maxage seconds applied to changelog, integrity and feeds. Native POST /update/check never uses public s-maxage.",
            "type": "integer"
          },
          "changelog_client_override": {
            "default": true,
            "description": "Whether client requests are allowed to override default changelog scope and layout.",
            "type": "boolean"
          },
          "changelog_include_platform_notes": {
            "description": "Whether to append platform slice notes to the version changelog.",
            "type": "boolean"
          },
          "changelog_include_revoked": {
            "description": "Whether to include revoked versions in historical changelogs.",
            "type": "boolean"
          },
          "changelog_layout": {
            "default": "both",
            "description": "Configured changelog layout style ('aggregated', 'structured', or 'both').",
            "enum": [
              "aggregated",
              "structured",
              "both"
            ],
            "type": "string"
          },
          "changelog_scope": {
            "default": "range_all",
            "description": "Configured changelog range scope ('range_all', 'range_platform', or 'target_only').",
            "enum": [
              "range_all",
              "range_platform",
              "target_only"
            ],
            "type": "string"
          },
          "compare_engine": {
            "description": "Version comparison engine ('semver' or 'integer'). Immutable once first version is published.",
            "enum": [
              "semver",
              "integer"
            ],
            "type": "string"
          },
          "cors_origins": {
            "description": "Allowed CORS origins for browser-based web clients or extensions.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "created_at": {
            "description": "Timestamp when the project was created (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "default_locale": {
            "description": "Denormalized copy of the default project language code. Required on POST create; PATCH upserts the language row and flips is_default.",
            "maxLength": 32,
            "minLength": 2,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{1,31}$",
            "type": "string"
          },
          "device_id_policy": {
            "description": "Storage policy for device identifiers: 'hashed' (HMAC-SHA256), 'raw', or 'none'.",
            "enum": [
              "hashed",
              "raw",
              "none"
            ],
            "type": "string"
          },
          "store_token": {
            "description": "Plaintext only when set on this write",
            "type": "string"
          },
          "force_https": {
            "description": "When true, client downloads and redirects enforce HTTPS URLs.",
            "type": "boolean"
          },
          "gray_weight_tenure_activity": {
            "default": true,
            "description": "When true (default), auto gray admission ranks by tenure×recency. When false, created_at,id ASC.",
            "type": "boolean"
          },
          "has_store_token": {
            "description": "Indicates whether a dedicated store authentication token is configured.",
            "type": "boolean"
          },
          "has_signing_private_key": {
            "description": "True if the server possesses the private key for signing release manifests.",
            "type": "boolean"
          },
          "minimum_supported_version": {
            "description": "Global floor version string. Clients below this are forced to update (is_mandatory=true).",
            "nullable": true,
            "type": "string"
          },
          "name": {
            "description": "Human-readable display title. Not unique and never used as project_ref. Omitted on create defaults to slug.",
            "maxLength": 128,
            "type": "string"
          },
          "rate_limit": {
            "additionalProperties": true,
            "description": "Default bag: check_per_device_per_minute=60, check_per_ip_per_minute=120, store_per_ip_per_minute=300, diff_per_device_per_minute=20, diff_per_ip_per_minute=60, telemetry_per_device_per_minute=30, ci_per_token_per_minute=600. 429 is enforced in a later task.",
            "type": "object"
          },
          "require_client_token": {
            "description": "When true, update checks and downloads require a valid ProjectToken in the header.",
            "type": "boolean"
          },
          "signed_url_ttl_seconds": {
            "default": 0,
            "description": "TTL in seconds for short-lived signed download URLs of private-storage projects (docs/app-init.md 13.7). 0 means the instance default of 3600 (1 hour). Path and filename stay stable; the signature lives only in the query (exp, sig).",
            "minimum": 0,
            "type": "integer"
          },
          "signing_algo": {
            "description": "Cryptographic signing algorithm for manifests and check responses ('ed25519' or 'rsa').",
            "enum": [
              "ed25519",
              "rsa-sha256"
            ],
            "type": "string"
          },
          "signing_public_key": {
            "description": "PEM-encoded public key used for response signature verification.",
            "type": "string"
          },
          "signing_private_key": {
            "description": "PEM-encoded private key. Write-only; never returned on GET or list.",
            "type": "string",
            "writeOnly": true
          },
          "slug": {
            "description": "URL-safe project identifier (alphanumeric, dashes, underscores; 3-64 characters).",
            "type": "string"
          },
          "slug_alias_retention_days": {
            "default": 365,
            "description": "0 means aliases never expire",
            "type": "integer"
          },
          "telemetry_retention_days": {
            "default": 90,
            "description": "Days to retain telemetry events. Default 90. Negative values are rejected; 0 is treated as 90.",
            "minimum": 0,
            "type": "integer"
          },
          "stats": {
            "$ref": "#/components/schemas/ProjectStats"
          },
          "storage_bucket": {
            "description": "Target object storage bucket name for project artifacts. Hidden in the admin UI when storage_driver is local.",
            "nullable": true,
            "type": "string"
          },
          "storage_driver": {
            "description": "Process-wide object storage driver. Read-only; not a per-project setting.",
            "enum": [
              "local",
              "s3"
            ],
            "readOnly": true,
            "type": "string"
          },
          "storage_prefix": {
            "description": "Optional path prefix. After trim and stripping leading/trailing slashes, no path segment may equal the project slug (case-insensitive). Empty is allowed. Does not rewrite ArtifactObjectKey.",
            "nullable": true,
            "type": "string"
          },
          "storage_visibility": {
            "description": "Storage object visibility. Writes must be public; private is rejected with 400. Existing private rows may still appear on GET until patched.",
            "enum": [
              "public",
              "private"
            ],
            "type": "string"
          },
          "updated_at": {
            "description": "Timestamp when the project settings were last modified (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "uuid": {
            "description": "Immutable unique identifier (UUID v4) of the project.",
            "format": "uuid",
            "type": "string"
          },
          "webhook_secret_reset": {
            "description": "Set true on PATCH to rotate the webhook signing secret. Never returned in GET or list responses.",
            "type": "boolean",
            "writeOnly": true
          },
          "webhook_url": {
            "description": "HTTPS endpoint notified via signed POST webhook upon version publication or revocation.",
            "nullable": true,
            "type": "string"
          },
          "file_list_max_files": {
            "description": "Per-project file_list pending-file cap. 0 inherits the platform ceiling (file_list_max_files_limit).",
            "type": "integer",
            "default": 0,
            "minimum": 0
          },
          "file_list_max_files_limit": {
            "description": "Read-only platform ceiling for file_list.max_files. PATCH file_list_max_files above this value is 400.",
            "type": "integer",
            "readOnly": true
          },
          "changelog_default_entries": {
            "type": "integer",
            "default": 5,
            "minimum": 1,
            "description": "Changelog entries when from_version is omitted. Must be 1…changelog_default_entries_limit and not exceed the effective max."
          },
          "changelog_max_entries": {
            "type": "integer",
            "default": 0,
            "minimum": 0,
            "description": "Changelog (from, to] truncation cap. 0 inherits changelog_max_entries_limit. PATCH above the instance ceiling is 400."
          },
          "changelog_default_entries_limit": {
            "type": "integer",
            "readOnly": true,
            "description": "Read-only instance changelog.default_entries ceiling."
          },
          "changelog_max_entries_limit": {
            "type": "integer",
            "readOnly": true,
            "description": "Read-only instance changelog.max_entries ceiling."
          }
        },
        "type": "object"
      },
      "ProjectLanguage": {
        "description": "Per-project language row used by announcement and changelog editors.",
        "properties": {
          "code": {
            "description": "Language code as typed (case preserved, e.g. zh-CN). Unique per project case-insensitively.",
            "maxLength": 32,
            "minLength": 2,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{1,31}$",
            "type": "string"
          },
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "display_name": {
            "description": "Optional operator label. Empty string means the UI should show code.",
            "maxLength": 64,
            "type": "string"
          },
          "id": {
            "description": "Unique language row identifier (UUID).",
            "format": "uuid",
            "type": "string"
          },
          "is_default": {
            "description": "Exactly one language per project is default. Mirrors projects.default_locale.",
            "type": "boolean"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "sort_order": {
            "description": "List order, ascending.",
            "type": "integer"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProjectLatestVersion": {
        "properties": {
          "channel": {
            "type": "string"
          },
          "status": {
            "enum": [
              "published",
              "deprecated"
            ],
            "type": "string"
          },
          "version": {
            "description": "Display version (semver if set, otherwise integer).",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProjectMember": {
        "properties": {
          "admin_id": {
            "format": "uuid",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "role": {
            "enum": [
              "owner",
              "admin"
            ],
            "type": "string"
          },
          "username": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProjectStats": {
        "additionalProperties": false,
        "description": "Aggregated catalog, storage, token, telemetry and 7-day active client counts for admin list/get.",
        "properties": {
          "active_7d": {
            "description": "Distinct namebook devices with last_check_at in the last 7 days.",
            "type": "integer"
          },
          "artifact_count": {
            "type": "integer"
          },
          "channels": {
            "type": "integer"
          },
          "ci_tokens": {
            "$ref": "#/components/schemas/ProjectTokenCounts"
          },
          "hw_revs": {
            "type": "integer"
          },
          "latest_version": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProjectLatestVersion"
              }
            ],
            "nullable": true
          },
          "matrix_rows": {
            "type": "integer"
          },
          "project_tokens": {
            "$ref": "#/components/schemas/ProjectTokenCounts"
          },
          "storage_bytes": {
            "description": "Sum of artifact size once per distinct storage_key (reuse-safe).",
            "type": "integer"
          },
          "telemetry": {
            "$ref": "#/components/schemas/ProjectTelemetryCounts"
          },
          "versions": {
            "$ref": "#/components/schemas/ProjectVersionCounts"
          }
        },
        "type": "object"
      },
      "ProjectTelemetryCounts": {
        "properties": {
          "failed_24h": {
            "type": "integer"
          },
          "installed_24h": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ProjectToken": {
        "description": "Scoped API token associated with a project for automated integrations.",
        "properties": {
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "description": "Expiration timestamp (UTC ISO-8601), or null if non-expiring.",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "fingerprint": {
            "description": "SHA-256 fingerprint for token identification.",
            "type": "string"
          },
          "id": {
            "description": "Unique token identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "name": {
            "description": "Descriptive label for this token.",
            "type": "string"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "scopes": {
            "description": "Granted permission scopes: 'project:read', 'artifact:write', 'release:publish', 'project:admin'.",
            "items": {
              "enum": [
                "project:read",
                "artifact:write",
                "release:publish",
                "project:admin"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "token": {
            "description": "Plaintext kv_… shown only on create",
            "type": "string"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProjectTokenCounts": {
        "properties": {
          "active": {
            "description": "Tokens with null expiry or expires_at in the future.",
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ProjectVersionCounts": {
        "properties": {
          "deprecated": {
            "type": "integer"
          },
          "draft": {
            "type": "integer"
          },
          "published": {
            "type": "integer"
          },
          "revoked": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PutManifestRequest": {
        "description": "Request payload containing file entries to build or update a multi-file manifest.",
        "properties": {
          "entries": {
            "description": "Array of file entry definitions.",
            "items": {
              "$ref": "#/components/schemas/ManifestEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "entries"
        ],
        "type": "object"
      },
      "StatusOutput": {
        "additionalProperties": false,
        "description": "Health response. status is process liveness; ready is database and storage.",
        "properties": {
          "ready": {
            "description": "True when PostgreSQL Ping and object-storage Head of the probe key both succeed.",
            "type": "boolean"
          },
          "status": {
            "description": "Process status; ok while the listener is up.",
            "example": "ok",
            "type": "string"
          }
        },
        "required": [
          "ready",
          "status"
        ],
        "type": "object"
      },
      "StoreListing": {
        "additionalProperties": false,
        "description": "Project store listing (project_store_listings). Protocol is Adapter.Protocol() (sparkle, electron, …), not UI-old electron-updater. Duplicate (protocol, slug) is 400.",
        "properties": {
          "arch": {
            "description": "Optional pin; non-empty ignores conflicting query arch.",
            "nullable": true,
            "type": "string"
          },
          "channel": {
            "description": "Optional pin; non-empty ignores conflicting query channel.",
            "nullable": true,
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "store_url": {
            "description": "Relative store URL including listing slug and the protocol default document.",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "identifiers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Protocol identifier bag (bundle id, PackageIdentifier, homepage, …).",
            "type": "object"
          },
          "manifest_path": {
            "description": "Required when package_source is manifest_path; relative manifest path.",
            "type": "string"
          },
          "os": {
            "description": "Optional pin; non-empty ignores conflicting query os.",
            "nullable": true,
            "type": "string"
          },
          "package_source": {
            "enum": [
              "line_full",
              "manifest_path"
            ],
            "type": "string"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          },
          "protocol": {
            "description": "Adapter Protocol() name: sparkle, electron, tauri, squirrel, clickonce, appimage, winget, msix, fdroid.",
            "type": "string"
          },
          "slug": {
            "description": "Feed identity; same rules as channel slug [a-z0-9-]{3,64}, no underscore.",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "protocol",
          "slug",
          "enabled",
          "package_source",
          "store_url"
        ],
        "type": "object"
      },
      "UploadArtifactInput": {
        "description": "Metadata for creating or presigning direct artifact uploads.",
        "properties": {
          "artifact_signature": {
            "description": "Detached cryptographic signature over the file bytes.",
            "type": "string"
          },
          "compatible_hw_revs": {
            "description": "List of compatible hardware revisions.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "filename": {
            "description": "Stable artifact file name.",
            "type": "string"
          },
          "hw_rev": {
            "description": "Hardware revision slug if variant-specific.",
            "type": "string"
          },
          "max_hw_rev": {
            "description": "Maximum compatible hardware revision.",
            "type": "string"
          },
          "md5": {
            "description": "Expected hex-encoded MD5 checksum.",
            "type": "string"
          },
          "min_hw_rev": {
            "description": "Minimum compatible hardware revision.",
            "type": "string"
          },
          "sha256": {
            "description": "Expected hex-encoded SHA-256 checksum.",
            "type": "string"
          },
          "sha512": {
            "description": "Expected hex-encoded SHA-512 checksum.",
            "type": "string"
          },
          "size": {
            "description": "Byte length of the artifact file.",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Version": {
        "description": "Project-level software release containing version identifiers, release notes, and incremental gray state.",
        "properties": {
          "actual_percent": {
            "description": "Live gray actual coverage (allowlisted/N*100) while gray is in progress; 100 after full push. Omitted on drafts that never started gray.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "auto_publish_when": {
            "$ref": "#/components/schemas/AutoPublishRule",
            "description": "Optional auto-publish gating rule."
          },
          "changelog": {
            "$ref": "#/components/schemas/ChangelogMap",
            "description": "Locale-keyed release notes as stored on the Version (GET)."
          },
          "channel": {
            "description": "Target distribution channel slug (e.g. 'stable', 'beta').",
            "type": "string"
          },
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "git_commit": {
            "description": "Git commit SHA associated with this build.",
            "nullable": true,
            "type": "string"
          },
          "git_log_from": {
            "description": "Starting git commit SHA for automatically generated changelog.",
            "nullable": true,
            "type": "string"
          },
          "git_log_to": {
            "description": "Ending git commit SHA for automatically generated changelog.",
            "nullable": true,
            "type": "string"
          },
          "git_tag": {
            "description": "Git tag associated with this build.",
            "nullable": true,
            "type": "string"
          },
          "gray_completed_at": {
            "description": "When gray completed (full push). Null means allowlist-only.",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "gray_interval_seconds": {
            "description": "Seconds between coverage ticks. k = floor(elapsed / interval).",
            "minimum": 1,
            "type": "integer"
          },
          "gray_start_percent": {
            "description": "Starting gray coverage percent at t=0. 100 (default) publishes as full push.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "gray_started_at": {
            "description": "When incremental gray started (publish time).",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "gray_step_percent": {
            "description": "Coverage percent added after each interval tick.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "id": {
            "description": "Unique version identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "is_critical": {
            "description": "True if this release contains urgent security fixes; forces immediate update and ignores gray rollout.",
            "type": "boolean"
          },
          "is_lts": {
            "description": "True if this version is marked as a Long-Term Support release.",
            "type": "boolean"
          },
          "lines": {
            "description": "Platform slices included on GET version detail.",
            "items": {
              "$ref": "#/components/schemas/VersionLine"
            },
            "type": "array"
          },
          "min_source_version": {
            "description": "Oldest source version permitted to upgrade directly to this version without passing through an intermediate.",
            "nullable": true,
            "type": "string"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "publish_time": {
            "description": "UTC timestamp when the version was published.",
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "description": "Lifecycle state: 'draft', 'published', 'deprecated', 'revoked'.",
            "enum": [
              "draft",
              "published",
              "deprecated",
              "revoked"
            ],
            "type": "string"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "version_integer": {
            "description": "Integer build number (must be unique within the project).",
            "nullable": true,
            "type": "integer"
          },
          "version_semver": {
            "description": "Semantic version string compliant with SemVer 2.0 (unique ignoring build metadata).",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "VersionExists": {
        "description": "Response indicating whether a specific version exists in the project repository.",
        "properties": {
          "channel": {
            "description": "Distribution channel of the existing version.",
            "type": "string"
          },
          "exists": {
            "description": "True if the version exists in this project.",
            "type": "boolean"
          },
          "id": {
            "description": "UUID of the resolved version.",
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "description": "Current lifecycle status of the version.",
            "type": "string"
          }
        },
        "required": [
          "exists"
        ],
        "type": "object"
      },
      "VersionLine": {
        "description": "Platform-specific slice (os, arch) belonging to a Version.",
        "properties": {
          "arch": {
            "description": "CPU architecture identifier.",
            "type": "string"
          },
          "artifacts": {
            "description": "Artifacts on this platform slice (present on GET .../lines).",
            "items": {
              "$ref": "#/components/schemas/Artifact"
            },
            "type": "array"
          },
          "created_at": {
            "description": "Creation timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Unique platform slice identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "min_api_level": {
            "description": "Minimum API level for this line. Combined with min_os using AND when both are set.",
            "minimum": 0,
            "nullable": true,
            "type": "integer"
          },
          "min_os": {
            "description": "Minimum operating system for this line (digits with optional dots). Null means unrestricted.",
            "nullable": true,
            "type": "string"
          },
          "os": {
            "description": "Operating system identifier.",
            "type": "string"
          },
          "platform_notes": {
            "description": "Platform-specific release notes or installation instructions.",
            "type": "string"
          },
          "packs_ready_at": {
            "description": "When system preheat (auto_delta, channel × delta_source_count) finished. Null means check/feed cannot see this line yet.",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "project_id": {
            "description": "Owning project UUID.",
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "description": "Slice readiness state: 'uploading', 'processing', 'ready', 'failed', 'yanked', 'disabled'.",
            "enum": [
              "pending",
              "ready",
              "disabled",
              "yanked"
            ],
            "type": "string"
          },
          "updated_at": {
            "description": "Last modification timestamp (UTC ISO-8601).",
            "format": "date-time",
            "type": "string"
          },
          "version_id": {
            "description": "Owning Version UUID.",
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "VersionLineCreateInput": {
        "description": "Declare a platform slice. When the project matrix is non-empty, os/arch must match a matrix row (400 otherwise).",
        "properties": {
          "arch": {
            "description": "Target CPU architecture.",
            "type": "string"
          },
          "min_api_level": {
            "description": "Optional minimum API level for the new line.",
            "minimum": 0,
            "type": "integer"
          },
          "min_os": {
            "description": "Minimum operating system required for this slice.",
            "type": "string"
          },
          "os": {
            "description": "Target operating system.",
            "type": "string"
          },
          "platform_notes": {
            "description": "Optional platform release notes.",
            "type": "string"
          }
        },
        "required": [
          "os",
          "arch"
        ],
        "type": "object"
      },
      "VersionLineListOutput": {
        "description": "Envelope returned by GET /api/v1/admin/projects/{project_ref}/versions/{version}/lines.",
        "properties": {
          "lines": {
            "description": "Platform slices for the version.",
            "items": {
              "$ref": "#/components/schemas/VersionLine"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "VersionListOutput": {
        "description": "Envelope returned by GET /api/v1/admin/projects/{project_ref}/versions. latest is present only when latest=true (or 1) together with os and arch.",
        "properties": {
          "latest": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProjectLatestVersion"
              }
            ],
            "description": "Present only when latest=true|1 and both os and arch are set. Max published+ready version for that pair, or null if none. Omitted on filtered and unfiltered lists.",
            "nullable": true
          },
          "versions": {
            "description": "Project versions after AND filters (channel, status, os, arch). os+arch means the version has that line in any status. List items omit full line payloads.",
            "items": {
              "$ref": "#/components/schemas/Version"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "VersionPatchInput": {
        "description": "Request payload to update release notes or metadata on an existing version.",
        "properties": {
          "auto_publish_when": {
            "$ref": "#/components/schemas/AutoPublishRule",
            "description": "Optional auto-publish gating rule."
          },
          "changelog": {
            "description": "Optional default changelog Markdown string (handler field changelog *string). Locale map goes in changelog_i18n.",
            "type": "string"
          },
          "changelog_i18n": {
            "$ref": "#/components/schemas/ChangelogMap",
            "description": "Locale-keyed changelog written on PUT/PATCH."
          },
          "git_commit": {
            "description": "Updated Git commit hash.",
            "type": "string"
          },
          "git_log_from": {
            "description": "Start git commit for changelog range.",
            "type": "string"
          },
          "git_log_to": {
            "description": "End git commit for changelog range.",
            "type": "string"
          },
          "git_tag": {
            "description": "Updated Git tag.",
            "type": "string"
          },
          "is_critical": {
            "description": "Update critical status.",
            "type": "boolean"
          },
          "is_lts": {
            "description": "Update LTS status.",
            "type": "boolean"
          },
          "min_source_version": {
            "description": "Update minimum direct source version.",
            "type": "string"
          },
          "version_integer": {
            "description": "Integer build number.",
            "type": "integer"
          },
          "version_semver": {
            "description": "SemVer 2.0 formatted version string.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "VersionPutInput": {
        "description": "Request payload to idempotently create or update a draft version.",
        "properties": {
          "auto_publish_when": {
            "$ref": "#/components/schemas/AutoPublishRule",
            "description": "Optional auto-publish gating rule."
          },
          "changelog": {
            "description": "Optional default changelog Markdown string (handler field changelog *string). Locale map goes in changelog_i18n.",
            "type": "string"
          },
          "changelog_i18n": {
            "$ref": "#/components/schemas/ChangelogMap",
            "description": "Locale-keyed changelog written on PUT/PATCH."
          },
          "channel": {
            "description": "Distribution channel slug.",
            "type": "string"
          },
          "git_commit": {
            "description": "Git commit hash.",
            "type": "string"
          },
          "git_log_from": {
            "description": "Start git commit for changelog range.",
            "type": "string"
          },
          "git_log_to": {
            "description": "End git commit for changelog range.",
            "type": "string"
          },
          "git_tag": {
            "description": "Git tag reference.",
            "type": "string"
          },
          "gray_interval_seconds": {
            "description": "Seconds between coverage ticks. k = floor(elapsed / interval).",
            "minimum": 1,
            "type": "integer"
          },
          "gray_start_percent": {
            "description": "Starting gray coverage percent at t=0. 100 (default) publishes as full push.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "gray_step_percent": {
            "description": "Coverage percent added after each interval tick.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "is_critical": {
            "description": "Mark version as critical update (disables gray rollout).",
            "type": "boolean"
          },
          "is_lts": {
            "description": "Mark version as Long-Term Support.",
            "type": "boolean"
          },
          "min_source_version": {
            "description": "Oldest version that can update directly.",
            "type": "string"
          },
          "version_integer": {
            "description": "Integer build number.",
            "type": "integer"
          },
          "version_semver": {
            "description": "SemVer 2.0 formatted version string.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "WebhookDelivery": {
        "description": "Audit log of an HTTP webhook notification sent upon version lifecycle events.",
        "properties": {
          "attempts": {
            "description": "Number of delivery attempts made.",
            "type": "integer"
          },
          "created_at": {
            "description": "Timestamp when the webhook event was generated.",
            "format": "date-time",
            "type": "string"
          },
          "delivered_at": {
            "description": "Timestamp when the webhook was successfully delivered.",
            "format": "date-time",
            "type": "string"
          },
          "event": {
            "description": "Event type: 'version.published', 'version.revoked', 'line.ready'.",
            "enum": [
              "version.published",
              "version_line.ready",
              "version.revoked"
            ],
            "type": "string"
          },
          "id": {
            "description": "Unique delivery record identifier (UUID v4).",
            "format": "uuid",
            "type": "string"
          },
          "last_error": {
            "description": "Error message from the last delivery attempt.",
            "type": "string"
          },
          "last_status_code": {
            "description": "HTTP status code received from the destination endpoint.",
            "type": "integer"
          },
          "line_id": {
            "description": "Associated version line UUID if line-specific.",
            "format": "uuid",
            "type": "string"
          },
          "payload": {
            "description": "Event data envelope body as delivered",
            "type": "object"
          },
          "project_id": {
            "description": "ID of the owning project.",
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "description": "Delivery state: 'pending', 'delivered', 'failed'.",
            "enum": [
              "pending",
              "delivered",
              "failed"
            ],
            "type": "string"
          },
          "version_id": {
            "description": "Associated version UUID.",
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "WebhookDeliveryListOutput": {
        "description": "Paginated list of webhook delivery records.",
        "properties": {
          "deliveries": {
            "description": "List of webhook delivery attempts.",
            "items": {
              "$ref": "#/components/schemas/WebhookDelivery"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Cursor token for retrieving the next page of deliveries.",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "bearerFormat": "opaque",
        "description": "Opaque administrator session token issued after completing login 2FA. Sent as Authorization: Bearer. Pending 2FA tokens use the same header on /auth/2fa/* enrollment and verify routes.",
        "scheme": "bearer",
        "type": "http"
      },
      "projectTokenAuth": {
        "description": "Project-scoped API token passed via X-Project-Token header or Authorization: Bearer <token>.",
        "in": "header",
        "name": "X-Project-Token",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "KiriVers admin-plane API: session authentication and 2FA, project and version management, artifacts, gray rollout, registered clients, announcements, GeoIP, and store listings. Software-client traffic (check, download, feeds) lives on the client plane.",
    "title": "KiriVers Admin API",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "paths": {
    "/api/v1/admin/admins": {
      "get": {
        "description": "Lists all registered instance administrator accounts. Requires instance:admin bearer authorization. Platform admin session only.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminListOutput"
                }
              }
            },
            "description": "List of administrator accounts."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN platform admin required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List instance admins",
        "tags": [
          "Admins"
        ]
      },
      "post": {
        "description": "Creates a new instance administrator account with bcrypt password. Requires instance:admin authorization. Platform admin session only.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminWriteInput"
              }
            }
          },
          "description": "New administrator account credentials.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Admin"
                }
              }
            },
            "description": "Administrator created successfully."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN platform admin required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create instance admin",
        "tags": [
          "Admins"
        ]
      }
    },
    "/api/v1/admin/admins/{id}": {
      "delete": {
        "description": "Deletes an administrator account. The last remaining administrator cannot be deleted (returns 409 LAST_ADMIN). Requires instance:admin authorization.",
        "parameters": [
          {
            "description": "Unique resource UUID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN platform admin required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete instance admin",
        "tags": [
          "Admins"
        ]
      },
      "patch": {
        "description": "Updates username and/or password of an existing administrator account. Requires instance:admin authorization.",
        "parameters": [
          {
            "description": "Unique resource UUID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminPatchInput"
              }
            }
          },
          "description": "Updated administrator account parameters.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Admin"
                }
              }
            },
            "description": "Administrator updated successfully."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN platform admin required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update instance admin",
        "tags": [
          "Admins"
        ]
      }
    },
    "/api/v1/admin/auth/2fa": {
      "get": {
        "description": "TOTP flag, remaining recovery codes, and passkey list for the full session account.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Admin2FAStatusOutput"
                }
              }
            },
            "description": "2FA status."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Current admin 2FA status",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/passkeys": {
      "get": {
        "description": "Passkeys for the current administrator.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminPasskeyListOutput"
                }
              }
            },
            "description": "Passkey list."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List passkeys",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/passkeys/begin": {
      "post": {
        "description": "Full session. Requires confirmed TOTP.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminWebAuthnOptionsOutput"
                }
              }
            },
            "description": "WebAuthn ceremony options."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_READY"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Begin passkey registration",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/passkeys/finish": {
      "post": {
        "description": "Stores a new passkey. Does not revoke other sessions.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminWebAuthnFinishInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Success with empty body."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_READY"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Finish passkey registration",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/passkeys/{id}": {
      "delete": {
        "description": "Removes one passkey. Does not revoke sessions or remove TOTP.",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Success with empty body."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a passkey",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/recovery/ack": {
      "post": {
        "description": "Required after first TOTP confirm before a full session can be issued.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminRecoveryAckInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "2FA or enrollment step result."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Acknowledge recovery codes",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/recovery/regenerate": {
      "post": {
        "description": "Invalidates unused codes and returns a new set once.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminRecoveryCodesOutput"
                }
              }
            },
            "description": "New recovery codes."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Regenerate recovery codes",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/skip-passkey": {
      "post": {
        "description": "Issues a full session from optional_passkey stage.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "2FA or enrollment step result."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Skip optional passkey",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/totp/confirm": {
      "post": {
        "description": "Confirms pending TOTP and returns recovery codes once.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminTOTPCodeInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "2FA or enrollment step result."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "TOTP_RATE_LIMITED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm TOTP enrollment",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/totp/rotate/confirm": {
      "post": {
        "description": "Replaces the confirmed TOTP secret. Does not revoke other sessions.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminTOTPCodeInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Success with empty body."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "TOTP_RATE_LIMITED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm TOTP rotation",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/totp/rotate/setup": {
      "post": {
        "description": "Writes a pending TOTP secret without replacing the confirmed secret yet.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminTOTPSetupOutput"
                }
              }
            },
            "description": "Pending TOTP secret."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Start TOTP rotation",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/totp/setup": {
      "post": {
        "description": "Restricted token, enroll_totp stage. Returns secret and otpauth_url.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "2FA or enrollment step result."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Start TOTP enrollment",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/verify": {
      "post": {
        "description": "TOTP or unused recovery code. Passkey assertions use the webauthn login routes.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Admin2FAVerifyInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "2FA or enrollment step result."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "TOTP_RATE_LIMITED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Verify second factor",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/webauthn/login/begin": {
      "post": {
        "description": "Restricted token, second_factor stage.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminWebAuthnOptionsOutput"
                }
              }
            },
            "description": "WebAuthn ceremony options."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_READY"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Begin passkey login",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/webauthn/login/finish": {
      "post": {
        "description": "Completes assertion and issues a full session. Not subject to TOTP period lockout.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminWebAuthnFinishInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "2FA or enrollment step result."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_READY"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Finish passkey login",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/webauthn/register/begin": {
      "post": {
        "description": "Restricted token, optional_passkey stage. Requires confirmed TOTP.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminWebAuthnOptionsOutput"
                }
              }
            },
            "description": "WebAuthn ceremony options."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_READY"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Begin passkey enrollment",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/2fa/webauthn/register/finish": {
      "post": {
        "description": "Registers a passkey and issues a full session.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminWebAuthnFinishInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "2FA or enrollment step result."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_READY"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Finish passkey enrollment",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/login": {
      "post": {
        "description": "Authenticates username and password. Returns a pending token for TOTP enrollment or second factor; a full session token is issued only after 2FA completes.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminLoginInput"
              }
            }
          },
          "description": "Administrator credentials.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLoginOutput"
                }
              }
            },
            "description": "Password accepted. status=pending with pending_token, or status=complete after 2FA."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "summary": "Instance admin password login",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/auth/logout": {
      "post": {
        "description": "Deletes the current full session token. Other sessions remain valid.",
        "responses": {
          "204": {
            "description": "Success with empty body."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Log out current session",
        "tags": [
          "Auth"
        ]
      }
    },
    "/api/v1/admin/build-info": {
      "get": {
        "description": "Build identity of this process for the console About dialog and footer: which version, revision and build this instance runs. Full admin session only, so anonymous visitors and pending (forced password change / 2FA enrollment) sessions learn nothing about the deployment.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuildInfo"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED missing Bearer"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN project or CI token"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Server build information",
        "tags": [
          "System"
        ]
      }
    },
    "/api/v1/admin/nodes": {
      "get": {
        "description": "Platform admin only. Lists process identity rows from Postgres (UUID, display name, last seen, CPU/memory). Nodes do not HTTP-report health.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClusterNodeListOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN platform admin required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List cluster nodes",
        "tags": [
          "Nodes"
        ]
      }
    },
    "/api/v1/admin/geoip/databases": {
      "get": {
        "description": "Platform admin only. Includes disabled rows, ordered by rank.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeoipListOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List GeoIP databases",
        "tags": [
          "GeoIP"
        ]
      },
      "post": {
        "description": "Platform admin only. multipart file + name + optional rank. At most 8 databases, 256MiB each. Object key geoip/{id}/{filename}.",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "format": "binary",
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "rank": {
                    "type": "integer"
                  }
                },
                "required": [
                  "file"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeoipDatabase"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload GeoIP MMDB",
        "tags": [
          "GeoIP"
        ]
      }
    },
    "/api/v1/admin/geoip/databases/{id}": {
      "delete": {
        "description": "Platform admin only. Deletes the object and row, then reloads readers.",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "GEOIP_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete GeoIP database",
        "tags": [
          "GeoIP"
        ]
      },
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "format": "uuid",
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Platform admin only. name / enabled / rank.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeoipPatchInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeoipDatabase"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "GEOIP_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Patch GeoIP database",
        "tags": [
          "GeoIP"
        ]
      }
    },
    "/api/v1/admin/jobs/{job_id}": {
      "get": {
        "description": "Polls status, progress, and results of an asynchronous background job.",
        "parameters": [
          {
            "description": "Asynchronous background job UUID.",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            },
            "description": "Job details"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "JOB_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get asynchronous job status and result",
        "tags": [
          "Jobs"
        ]
      }
    },
    "/api/v1/admin/projects": {
      "get": {
        "description": "Any complete admin session. Platform admins see every project; others see memberships only. Soft-deleted projects are omitted.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "projects": {
                      "items": {
                        "$ref": "#/components/schemas/Project"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED missing Bearer"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN project or CI token"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List projects",
        "tags": [
          "Projects"
        ]
      },
      "post": {
        "description": "Instance admin session only. Allocates UUID v4. Project Token and CI Token receive 403 FORBIDDEN. default_locale is required and seeds the first language row.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "changelog_client_override": {
                    "type": "boolean"
                  },
                  "changelog_include_platform_notes": {
                    "type": "boolean"
                  },
                  "changelog_include_revoked": {
                    "type": "boolean"
                  },
                  "changelog_layout": {
                    "type": "string"
                  },
                  "changelog_scope": {
                    "type": "string"
                  },
                  "compare_engine": {
                    "enum": [
                      "semver",
                      "integer"
                    ],
                    "type": "string"
                  },
                  "cors_origins": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "default_locale": {
                    "description": "Required. Seeds the project's single default language row. Do not omit.",
                    "maxLength": 32,
                    "minLength": 2,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{1,31}$",
                    "type": "string"
                  },
                  "device_id_policy": {
                    "enum": [
                      "hashed",
                      "raw",
                      "none"
                    ],
                    "type": "string"
                  },
                  "store_token": {
                    "type": "string"
                  },
                  "force_https": {
                    "type": "boolean"
                  },
                  "gray_weight_tenure_activity": {
                    "default": true,
                    "description": "When true (default), auto gray admission ranks by tenure×recency. When false, created_at,id ASC.",
                    "type": "boolean"
                  },
                  "minimum_supported_version": {
                    "nullable": true,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "owner_password": {
                    "format": "password",
                    "type": "string"
                  },
                  "owner_username": {
                    "description": "Optional project owner. With owner_password creates a non-platform account; without it attaches an existing account.",
                    "type": "string"
                  },
                  "rate_limit": {
                    "type": "object"
                  },
                  "require_client_token": {
                    "type": "boolean"
                  },
                  "signed_url_ttl_seconds": {
                    "description": "TTL in seconds for short-lived signed download URLs of private-storage projects. 0 means the instance default (3600).",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "signing_algo": {
                    "enum": [
                      "ed25519",
                      "rsa-sha256"
                    ],
                    "type": "string"
                  },
                  "signing_private_key": {
                    "type": "string"
                  },
                  "signing_public_key": {
                    "type": "string"
                  },
                  "slug": {
                    "pattern": "^[a-zA-Z0-9_-]{3,64}$",
                    "type": "string"
                  },
                  "slug_alias_retention_days": {
                    "type": "integer"
                  },
                  "telemetry_retention_days": {
                    "default": 90,
                    "description": "Days to retain telemetry events. Default 90. Negative values are rejected; 0 is treated as 90.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "cache_s_maxage_seconds": {
                    "type": "integer"
                  },
                  "file_list_max_files": {
                    "description": "Per-project file_list pending-file cap. 0 inherits the platform ceiling.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "storage_bucket": {
                    "type": "string"
                  },
                  "storage_prefix": {
                    "type": "string"
                  },
                  "storage_visibility": {
                    "description": "Must be public. private is 400 INVALID_REQUEST.",
                    "enum": [
                      "public",
                      "private"
                    ],
                    "type": "string"
                  },
                  "system_channel_names": {
                    "description": "Optional display names for the three system channels. Omitted fields fall back to English slugs.",
                    "properties": {
                      "alpha": {
                        "type": "string"
                      },
                      "beta": {
                        "type": "string"
                      },
                      "stable": {
                        "type": "string"
                      }
                    },
                    "type": "object"
                  },
                  "webhook_secret_reset": {
                    "type": "boolean"
                  },
                  "webhook_url": {
                    "type": "string"
                  },
                  "changelog_default_entries": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Changelog entries when from_version is omitted. Must not exceed changelog_default_entries_limit or the effective max."
                  },
                  "changelog_max_entries": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Changelog truncation cap. 0 inherits the instance max_entries."
                  }
                },
                "required": [
                  "slug",
                  "default_locale"
                ],
                "type": "object"
              }
            }
          },
          "description": "Project configuration parameters for creation.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Project"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST illegal slug or settings"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "SLUG_TAKEN"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create project",
        "tags": [
          "Projects"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}": {
      "delete": {
        "description": "Deletes a project and all associated channels, matrix rows, versions, and artifacts. Requires project:admin scope.",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Soft-delete project",
        "tags": [
          "Projects"
        ]
      },
      "get": {
        "description": "UUID and slug return equivalent bodies. Signing private key and token hashes are never listed.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Project"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get project",
        "tags": [
          "Projects"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "patch": {
        "description": "Changing slug writes an alias for the old name. PATCH compare_engine after any published Version returns 409 COMPARE_ENGINE_IMMUTABLE.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Project"
              }
            }
          },
          "description": "Updated project configuration properties."
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Project"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "SLUG_TAKEN or COMPARE_ENGINE_IMMUTABLE"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update project",
        "tags": [
          "Projects"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/announcements": {
      "get": {
        "description": "Returns all announcements for the project including drafts and out-of-window items, ordered by sort_order. Requires project:read.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "announcements": {
                      "items": {
                        "$ref": "#/components/schemas/AdminAnnouncement"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List announcements",
        "tags": [
          "Announcements"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Creates a draft announcement. Scope is one of seven: project / version / os / arch / version+os / version+arch / version+matrix. os+arch without version is 400. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "arch": {
                    "nullable": true,
                    "type": "string"
                  },
                  "content": {
                    "description": "Optional markdown body stored as a text column.",
                    "type": "string"
                  },
                  "ends_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "language": {
                    "description": "Language code for this row (one language per announcement).",
                    "type": "string"
                  },
                  "os": {
                    "nullable": true,
                    "type": "string"
                  },
                  "starts_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "subtitle": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "version_id": {
                    "description": "Version UUID to bind; omit or null for non-version scopes.",
                    "format": "uuid",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "language",
                  "title"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminAnnouncement"
                }
              }
            },
            "description": "Created as draft"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create announcement",
        "tags": [
          "Announcements"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/announcements/reorder": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "put": {
        "description": "Body ids must be a permutation of every announcement in the project. Rewrites sort_order to 0..n-1. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "ids": {
                    "items": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "ids"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "announcements": {
                      "items": {
                        "$ref": "#/components/schemas/AdminAnnouncement"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reorder announcements",
        "tags": [
          "Announcements"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/announcements/{announcement_id}": {
      "delete": {
        "description": "Hard delete. Requires project:admin.",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_FOUND or PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete announcement",
        "tags": [
          "Announcements"
        ]
      },
      "get": {
        "description": "Requires project:read.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminAnnouncement"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_FOUND or PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get announcement",
        "tags": [
          "Announcements"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "in": "path",
          "name": "announcement_id",
          "required": true,
          "schema": {
            "format": "uuid",
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Partial update including status, scope, scalar copy fields, and window. JSON null clears version_id/os/arch/timestamps. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "arch": {
                    "nullable": true,
                    "type": "string"
                  },
                  "content": {
                    "description": "Optional markdown body stored as a text column.",
                    "type": "string"
                  },
                  "ends_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "language": {
                    "type": "string"
                  },
                  "os": {
                    "nullable": true,
                    "type": "string"
                  },
                  "starts_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "draft",
                      "scheduled",
                      "published"
                    ],
                    "type": "string"
                  },
                  "subtitle": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "version_id": {
                    "description": "Version UUID to bind; JSON null clears version scope.",
                    "format": "uuid",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminAnnouncement"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_FOUND, PROJECT_NOT_FOUND, or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update announcement",
        "tags": [
          "Announcements"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/artifacts/cleanup": {
      "post": {
        "description": "Cleans up expired or aborted TUS uploads and unreferenced draft artifacts older than specified retention days.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Retention threshold in days (default: 90). Objects older than this are deleted.",
            "in": "query",
            "name": "retention_days",
            "required": false,
            "schema": {
              "default": 90,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CleanupOutput"
                }
              }
            },
            "description": "Cleanup completed successfully."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Cleanup expired or aborted upload sessions",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/artifacts/tus/{upload_id}": {
      "delete": {
        "description": "Aborts and removes an active TUS 1.0 upload session.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "TUS 1.0 upload session UUID.",
            "in": "path",
            "name": "upload_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Upload aborted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Abort TUS 1.0 upload",
        "tags": [
          "Artifacts"
        ]
      },
      "head": {
        "description": "Queries current byte offset and length of an active TUS 1.0 upload session.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "TUS 1.0 upload session UUID.",
            "in": "path",
            "name": "upload_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current upload offset"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UPLOAD_SESSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Query TUS 1.0 upload offset",
        "tags": [
          "Artifacts"
        ]
      },
      "patch": {
        "description": "Appends a chunk of binary data to an active TUS 1.0 upload session (C05-4).",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "TUS 1.0 upload session UUID.",
            "in": "path",
            "name": "upload_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "description": "Current byte offset of the file chunk in TUS 1.0 upload protocol.",
            "in": "header",
            "name": "Upload-Offset",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "MIME media type header for the request body.",
            "in": "header",
            "name": "Content-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "TUS protocol specification version (1.0.0).",
            "in": "header",
            "name": "Tus-Resumable",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Current byte offset at which the chunk begins.",
            "in": "header",
            "name": "Upload-Offset",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Current byte offset at which the chunk begins.",
            "in": "header",
            "name": "Upload-Offset",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Current byte offset at which the chunk begins.",
            "in": "header",
            "name": "Upload-Offset",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/offset+octet-stream": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          },
          "description": "Binary chunk stream.",
          "required": true
        },
        "responses": {
          "204": {
            "description": "Chunk written successfully; returns updated Upload-Offset header.",
            "headers": {
              "Tus-Resumable": {
                "description": "TUS protocol version (1.0.0).",
                "schema": {
                  "type": "string"
                }
              },
              "Upload-Offset": {
                "description": "New byte offset after appending chunk.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "CHECKSUM_MISMATCH"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "OFFSET_MISMATCH / ARTIFACT_IMMUTABLE"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload chunk via TUS 1.0",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/audit": {
      "get": {
        "description": "Retrieves paginated administrative audit logs tracking project modifications and version releases.",
        "parameters": [
          {
            "description": "Opaque cursor from next_cursor of the previous page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Maximum number of records to return per page.",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 50,
              "maximum": 500,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditListOutput"
                }
              }
            },
            "description": "Paginated audit records."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Insufficient scope."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Project not found."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List project audit events",
        "tags": [
          "Audit"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/channels": {
      "get": {
        "description": "New projects include system alpha/beta/stable with ranks 10/20/30. Ordered by stability_rank. Requires instance admin session or project:read.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "channels": {
                      "items": {
                        "$ref": "#/components/schemas/Channel"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List channels",
        "tags": [
          "Channels"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Requires instance admin session or project:admin. Slug lts is allowed and does not set Version is_lts. Underscore in slug is rejected.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "name": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "stability_rank": {
                    "type": "integer"
                  },
                  "token": {
                    "description": "Omit to keep, empty string to clear, non-empty to set plaintext + hash. Admin list/get always return token.",
                    "type": "string"
                  },
                  "unlisted": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "slug"
                ],
                "type": "object"
              }
            }
          },
          "description": "Channel definition parameters.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Channel"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "SLUG_TAKEN"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create custom channel",
        "tags": [
          "Channels"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/channels/{slug}": {
      "delete": {
        "description": "Deleting a system channel (stable/beta/alpha) returns 409 SYSTEM_CHANNEL, not 200.",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "SYSTEM_CHANNEL"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete custom channel",
        "tags": [
          "Channels"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Entity identifier slug (e.g. channel or hardware revision).",
          "in": "path",
          "name": "slug",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "System channels may be disabled. Requires project:admin or instance admin session.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "name": {
                    "type": "string"
                  },
                  "stability_rank": {
                    "type": "integer"
                  },
                  "token": {
                    "description": "Omit to keep, empty string to clear, non-empty to set plaintext + hash. Admin list/get always return token.",
                    "type": "string"
                  },
                  "unlisted": {
                    "type": "boolean"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Channel update parameters."
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Channel"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update channel",
        "tags": [
          "Channels"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/install-policy-rules": {
      "get": {
        "description": "Project-scope install policy template for one matrix pair. Unlisted paths default to OVERWRITE when a new Manifest is generated. Requires instance admin session or project:read.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallPolicyRulesOutput"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or INVALID_PATH"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get project install policy rules",
        "tags": [
          "InstallPolicy"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Canonical OS slug or alias; must already exist on the platform matrix.",
          "in": "query",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Canonical architecture slug or alias; must already exist on the platform matrix.",
          "in": "query",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "put": {
        "description": "Replace-all project-scope rules for the matrix pair. Does not rewrite published Manifests and does not invalidate catalog cache. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstallPolicyRulesInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallPolicyRulesOutput"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or INVALID_PATH"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace project install policy rules",
        "tags": [
          "InstallPolicy"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/install-policy-rules/reference": {
      "get": {
        "description": "Reference Manifest for the install-policy editor. Latest is CompareVersions over that channel's non-revoked versions (not GET versions?latest=true). Missing line still returns the version with empty entries. No non-revoked version returns version null.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallPolicyReferenceOutput"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or INVALID_PATH"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get install policy reference Manifest",
        "tags": [
          "InstallPolicy"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Channel slug used as the reference source. Default stable.",
          "in": "query",
          "name": "channel",
          "required": false,
          "schema": {
            "default": "stable",
            "type": "string"
          }
        },
        {
          "description": "Canonical OS slug or alias; must already exist on the platform matrix.",
          "in": "query",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Canonical architecture slug or alias; must already exist on the platform matrix.",
          "in": "query",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/channels/{slug}/install-policy-rules": {
      "get": {
        "description": "Channel-scope install policy rows plus D1 effective overlay for the matrix pair. Requires project:read.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallPolicyRulesOutput"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or INVALID_PATH"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get channel install policy rules",
        "tags": [
          "InstallPolicy"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Channel slug.",
          "in": "path",
          "name": "slug",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Canonical OS slug or alias; must already exist on the platform matrix.",
          "in": "query",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Canonical architecture slug or alias; must already exist on the platform matrix.",
          "in": "query",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "put": {
        "description": "Replace-all channel-scope rules for the matrix pair. Project-scope rows are unchanged. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstallPolicyRulesInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallPolicyRulesOutput"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or INVALID_PATH"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace channel install policy rules",
        "tags": [
          "InstallPolicy"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/ci-tokens": {
      "get": {
        "description": "Lists CI tokens for a project. Returns fingerprints only, never plaintext token.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "ci_tokens": {
                      "description": "Same list as tokens; handler returns both keys.",
                      "items": {
                        "$ref": "#/components/schemas/CIToken"
                      },
                      "type": "array"
                    },
                    "tokens": {
                      "items": {
                        "$ref": "#/components/schemas/CIToken"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List CI tokens",
        "tags": [
          "Projects"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Requires project:admin. Plaintext kvc_… is returned once.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "expires_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "scopes": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "name",
                  "scopes"
                ],
                "type": "object"
              }
            }
          },
          "description": "CI token creation parameters.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CIToken"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue CI token",
        "tags": [
          "Projects"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/ci-tokens/{token_id}": {
      "delete": {
        "description": "Revokes and permanently deletes a CI runner token.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Unique token UUID.",
            "in": "path",
            "name": "token_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or TOKEN_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke CI token",
        "tags": [
          "Projects"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/ci/releases": {
      "post": {
        "description": "Automated CI runner endpoint to upload a multi-architecture or multi-file release bundle. The server asynchronously unpacks the bundle zip into os/arch platform slices, automatically detects single_file or multi_file layout, generates manifests, and publishes if auto_publish_when is satisfied.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Unique idempotency key preventing duplicate processing within 24 hours.",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "archive": {
                    "description": "Alias of file.",
                    "format": "binary",
                    "type": "string"
                  },
                  "auto_publish_when": {
                    "description": "JSON string of AutoPublishRule.",
                    "type": "string"
                  },
                  "bundle": {
                    "description": "Alias of file.",
                    "format": "binary",
                    "type": "string"
                  },
                  "changelog": {
                    "description": "Release notes in Markdown.",
                    "type": "string"
                  },
                  "channel": {
                    "description": "Target distribution channel (default: stable).",
                    "type": "string"
                  },
                  "file": {
                    "description": "Release bundle zip (form field file).",
                    "format": "binary",
                    "type": "string"
                  },
                  "json": {
                    "description": "Alias of metadata JSON string.",
                    "type": "string"
                  },
                  "metadata": {
                    "description": "JSON string of CIRunReleaseInput fields (version, channel, changelog, publish, auto_publish_when).",
                    "type": "string"
                  },
                  "publish": {
                    "description": "Whether to publish automatically ('true' or 'false').",
                    "type": "string"
                  },
                  "version": {
                    "description": "Target release version when metadata is omitted.",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Release bundle. multipart/form-data is the UI path: file/bundle/archive plus metadata JSON and/or version/channel/changelog/publish. application/json with bundle_base64/archive_base64 and application/zip streams are also accepted by the handler.",
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CIReleasesOutput"
                }
              }
            },
            "description": "Bundle accepted for asynchronous processing; poll GET /api/v1/admin/jobs/{job_id} for completion."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or ZIP_LAYOUT_INVALID"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "One-click release via bundle archive upload",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/clients": {
      "get": {
        "description": "Paginated client registry for the project.",
        "parameters": [
          {
            "description": "Search last_version/os/arch/channel/ip and custom JSON text.",
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "os",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "arch",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "version",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "active_since",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientListOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List registered clients",
        "tags": [
          "Clients"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/clients/stats": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientBuckets"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Client list chart buckets",
        "tags": [
          "Clients"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/clients/{client_id}": {
      "delete": {
        "description": "Deletes the registry row and all gray allowlist entries for that device_hash in the project.",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "CLIENT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete registered client",
        "tags": [
          "Clients"
        ]
      },
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Client"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one registered client",
        "tags": [
          "Clients"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "in": "path",
          "name": "client_id",
          "required": true,
          "schema": {
            "format": "uuid",
            "type": "string"
          }
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/hw-revs": {
      "get": {
        "description": "Ordered by rank ascending.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "hw_revs": {
                      "items": {
                        "$ref": "#/components/schemas/HwRev"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List hardware revisions",
        "tags": [
          "Platforms"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Registers a new hardware revision timeline generation for physical devices.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "notes": {
                    "type": "string"
                  },
                  "rank": {
                    "type": "integer"
                  },
                  "slug": {
                    "type": "string"
                  }
                },
                "required": [
                  "slug"
                ],
                "type": "object"
              }
            }
          },
          "description": "Hardware revision generation parameters.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HwRev"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "SLUG_TAKEN"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create hardware revision",
        "tags": [
          "Platforms"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/hw-revs/{slug}": {
      "delete": {
        "description": "Deletes a hardware revision from the project catalog.",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or HW_REV_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete hardware revision",
        "tags": [
          "Platforms"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Entity identifier slug (e.g. channel or hardware revision).",
          "in": "path",
          "name": "slug",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Updates rank ordering or notes for a hardware revision.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "notes": {
                    "type": "string"
                  },
                  "rank": {
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Hardware revision update parameters."
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HwRev"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or HW_REV_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update hardware revision",
        "tags": [
          "Platforms"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/languages": {
      "get": {
        "description": "Ordered by sort_order then code. Envelope key languages. Requires instance admin session or project:read.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "languages": {
                      "items": {
                        "$ref": "#/components/schemas/ProjectLanguage"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List project languages",
        "tags": [
          "Languages"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Requires project:admin. Cap 16. Duplicate code (case-insensitive) returns 409 LANGUAGE_TAKEN. Setting is_default clears sibling defaults and writes projects.default_locale.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "code": {
                    "maxLength": 32,
                    "minLength": 2,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{1,31}$",
                    "type": "string"
                  },
                  "display_name": {
                    "maxLength": 64,
                    "type": "string"
                  },
                  "is_default": {
                    "type": "boolean"
                  },
                  "sort_order": {
                    "type": "integer"
                  }
                },
                "required": [
                  "code"
                ],
                "type": "object"
              }
            }
          },
          "description": "Language definition parameters.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectLanguage"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "LANGUAGE_TAKEN"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create project language",
        "tags": [
          "Languages"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/languages/{code}": {
      "delete": {
        "description": "Cannot delete the last language or the current default (400 INVALID_REQUEST). Does not rewrite announcement or changelog JSON. Requires project:admin.",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or LANGUAGE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete project language",
        "tags": [
          "Languages"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Language code (case-insensitive lookup, stored case preserved).",
          "in": "path",
          "name": "code",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Updates display_name, sort_order, and/or is_default. Code cannot be changed. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "display_name": {
                    "maxLength": 64,
                    "type": "string"
                  },
                  "is_default": {
                    "type": "boolean"
                  },
                  "sort_order": {
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Language update parameters."
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectLanguage"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or LANGUAGE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update project language",
        "tags": [
          "Languages"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/matrix": {
      "get": {
        "description": "Lists all platform matrix rows defining supported OS, CPU architectures, and package types.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "matrix": {
                      "items": {
                        "$ref": "#/components/schemas/PlatformMatrix"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform matrix rows",
        "tags": [
          "Platforms"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Stores canonical os/arch (darwin→macos, amd64→x86_64). Defaults: delta_algo=hdiffpatch, delta_source_count=3, fallback_arch empty. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "arch": {
                    "type": "string"
                  },
                  "delta_algo": {
                    "type": "string"
                  },
                  "delta_source_count": {
                    "type": "integer"
                  },
                  "fallback_arch": {
                    "type": "string"
                  },
                  "hw_variant_policy": {
                    "type": "string"
                  },
                  "minimum_supported_version": {
                    "nullable": true,
                    "type": "string"
                  },
                  "os": {
                    "type": "string"
                  },
                  "package_type": {
                    "enum": [
                      "single_file",
                      "multi_file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "os",
                  "arch",
                  "package_type"
                ],
                "type": "object"
              }
            }
          },
          "description": "Platform matrix row creation parameters.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformMatrix"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "MATRIX_EXISTS"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create platform matrix row",
        "tags": [
          "Platforms"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/matrix/{os}/{arch}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Target operating system slug (windows, linux, macos, android).",
          "in": "path",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target CPU architecture slug (x86_64, arm64, x86).",
          "in": "path",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Path os/arch aliases are canonicalized (darwin writes map to macos). Changing package_type after a published Version Line exists for that pair returns 409 PACKAGE_TYPE_IMMUTABLE.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlatformMatrix"
              }
            }
          },
          "description": "Platform matrix row update parameters."
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformMatrix"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or MATRIX_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PACKAGE_TYPE_IMMUTABLE"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update platform matrix row",
        "tags": [
          "Platforms"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/media": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Admin-authenticated multipart upload for changelog/announcement images and attachments. Field name file[] (also accepts file). Bytes go through storage.Backend; response is Vditor-compatible {code,msg,data.succMap} plus data.files[] with sha256/md5/sha512. URLs use ${site_url}. Max 10 MiB. Rejects empty files, text/html, image/svg+xml, and JavaScript MIME types. Requires project:admin.",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file[]": {
                    "description": "Files to upload (Vditor field name).",
                    "items": {
                      "format": "binary",
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "data": {
                      "properties": {
                        "errFiles": {
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "files": {
                          "description": "Per-file metadata including hashes. Kept alongside succMap for Vditor.",
                          "items": {
                            "$ref": "#/components/schemas/MediaUploadFile"
                          },
                          "type": "array"
                        },
                        "succMap": {
                          "additionalProperties": {
                            "type": "string"
                          },
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    "msg": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Vditor upload envelope. code=0 when at least one file succeeded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload Markdown media",
        "tags": [
          "Media"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/members": {
      "get": {
        "description": "Human admin session required. Platform admins and project members.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberListOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List project members",
        "tags": [
          "Members"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "role=owner only platform admin. role=admin platform admin or project owner. Last-owner rules do not apply to create.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberWriteInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectMember"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND ADMIN_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "USERNAME_TAKEN"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add project member",
        "tags": [
          "Members"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/members/{admin_id}": {
      "delete": {
        "description": "Platform can remove owner/admin; owner can remove admin only. Last owner → 400 LAST_OWNER.",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "LAST_OWNER"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "MEMBER_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove project member",
        "tags": [
          "Members"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "in": "path",
          "name": "admin_id",
          "required": true,
          "schema": {
            "format": "uuid",
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Platform admin only. Last owner cannot be demoted (400 LAST_OWNER).",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberPatchInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectMember"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or LAST_OWNER"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "MEMBER_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change member role",
        "tags": [
          "Members"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/platforms/catalog": {
      "get": {
        "description": "Lists preset operating systems and architectures plus aliases (darwin/osx→macos, amd64→x86_64). ipados is listed; CanonicalOS maps it to ios unless the project matrix contains os=ipados.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformCatalogOutput"
                }
              }
            },
            "description": "Platform catalog containing preset operating systems and CPU architectures."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Preset OS/Arch catalog",
        "tags": [
          "Platforms"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/node-sync": {
      "get": {
        "description": "Platform admin only. Per-node replica progress for this project (local-proxy bytes; S3-direct rows are ready without copy).",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NodeArtifactSyncListOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN platform admin required"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List per-node artifact sync for a project",
        "tags": [
          "Nodes"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/stats/series": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientDailySeriesOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Daily new and active client series",
        "tags": [
          "Clients"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/store-listings": {
      "get": {
        "description": "Admin CRUD for project_store_listings. Requires instance admin session or project:read. Envelope {listings:[]}.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "listings": {
                      "items": {
                        "$ref": "#/components/schemas/StoreListing"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List store listings",
        "tags": [
          "Store Listings"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Requires instance admin session or project:admin. Duplicate (protocol, slug) and illegal slug are 400 INVALID_REQUEST (not 409).",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "arch": {
                    "nullable": true,
                    "type": "string"
                  },
                  "channel": {
                    "nullable": true,
                    "type": "string"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "identifiers": {
                    "additionalProperties": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "manifest_path": {
                    "type": "string"
                  },
                  "os": {
                    "nullable": true,
                    "type": "string"
                  },
                  "package_source": {
                    "enum": [
                      "line_full",
                      "manifest_path"
                    ],
                    "type": "string"
                  },
                  "protocol": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreListing"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST (duplicate protocol+slug, illegal slug, unknown protocol, missing manifest_path)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create store listing",
        "tags": [
          "Store Listings"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/store-listings/{listing_id}": {
      "delete": {
        "description": "Removes the listing. The old feed URL then returns a plain-text 404.",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete store listing",
        "tags": [
          "Store Listings"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Store listing UUID.",
          "in": "path",
          "name": "listing_id",
          "required": true,
          "schema": {
            "format": "uuid",
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Partial update. Empty os/arch/channel string clears the pin. Requires project:admin.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "arch": {
                    "nullable": true,
                    "type": "string"
                  },
                  "channel": {
                    "nullable": true,
                    "type": "string"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "identifiers": {
                    "additionalProperties": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "manifest_path": {
                    "type": "string"
                  },
                  "os": {
                    "nullable": true,
                    "type": "string"
                  },
                  "package_source": {
                    "enum": [
                      "line_full",
                      "manifest_path"
                    ],
                    "type": "string"
                  },
                  "protocol": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreListing"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST (duplicate protocol+slug, illegal slug, unknown protocol, missing manifest_path)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update store listing",
        "tags": [
          "Store Listings"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/telemetry/devices/{device_hash}": {
      "delete": {
        "description": "DELETE admin telemetry device (docs/app-init.md 11.2, 13.11, C15-4). Deletes every telemetry event AND every gray-allowlist row (version-level and per-line) of the device hash within the project. Requires project:admin scope (or instance admin). Idempotent: an unknown hash succeeds with zero counts. Rate limiting does not apply to admin APIs.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Device identifier hash (HMAC hex under the hashed policy).",
            "in": "path",
            "name": "device_hash",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteTelemetryOutput"
                }
              }
            },
            "description": "Device telemetry and gray allowlist records deleted."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Insufficient scope."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Project not found."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete all telemetry events of one device hash (privacy deletion)",
        "tags": [
          "Telemetry"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/tokens": {
      "get": {
        "description": "Lists all active scoped API tokens created for this project.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "tokens": {
                      "items": {
                        "$ref": "#/components/schemas/ProjectToken"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List project tokens",
        "tags": [
          "Projects"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        }
      ],
      "post": {
        "description": "Requires instance admin session or project:admin on this project. Plaintext kv_… is returned once.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "expires_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "scopes": {
                    "items": {
                      "enum": [
                        "project:read",
                        "artifact:write",
                        "release:publish",
                        "project:admin"
                      ],
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "name",
                  "scopes"
                ],
                "type": "object"
              }
            }
          },
          "description": "Project API token creation parameters.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectToken"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue project token",
        "tags": [
          "Projects"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/tokens/{token_id}": {
      "delete": {
        "description": "Revokes and permanently deletes a project API token.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Unique token UUID.",
            "in": "path",
            "name": "token_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or TOKEN_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke project token",
        "tags": [
          "Projects"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions": {
      "get": {
        "description": "AND filters on channel, status, os, and arch. os+arch returns versions that have that line (any status) and never includes latest. Workbench published+ready+latest payload requires latest=true|1 together with os and arch.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Canonical or alias OS slug. Paired with arch, filters versions that have that line (any status).",
            "in": "query",
            "name": "os",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Canonical or alias arch slug. Must be paired with os to filter by line.",
            "in": "query",
            "name": "arch",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When true/1 with os and arch, return the published+ready workbench payload including latest.",
            "in": "query",
            "name": "latest",
            "required": false,
            "schema": {
              "enum": [
                "true",
                "1"
              ],
              "type": "string"
            }
          },
          {
            "description": "Target distribution channel (e.g. stable, beta, alpha).",
            "in": "query",
            "name": "channel",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by entity lifecycle status ('draft', 'published', 'deprecated', 'revoked').",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Maximum number of records to return per page.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "type": "integer"
            }
          },
          {
            "description": "Pagination offset integer for querying subsequent pages.",
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionListOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List versions",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}": {
      "delete": {
        "description": "Deletes a version. Published versions cannot be directly deleted (must revoke or yank).",
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "VERSION_NOT_DRAFT"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete draft version",
        "tags": [
          "Versions"
        ]
      },
      "get": {
        "description": "Retrieves comprehensive metadata for a specific version including status and release notes.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get version details",
        "tags": [
          "Versions"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Updates release notes, git metadata, or lifecycle parameters on a version.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VersionPatchInput"
              }
            }
          },
          "description": "Version metadata patch parameters."
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "GRAY_NOT_ALLOWED_ON_CRITICAL or INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "VERSION_NOT_DRAFT"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Patch version metadata",
        "tags": [
          "Versions"
        ]
      },
      "put": {
        "description": "Put version with specified integer and/or semver. Integer parsing normalizes leading zeros (010 == 10). SemVer must have prerelease equal to channel slug, or no prerelease for stable. Gray percentage is forbidden on critical versions.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VersionPutInput"
              }
            }
          },
          "description": "Idempotent draft version upsert parameters."
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "Draft version matched or updated"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "Draft version created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "ENGINE_MISMATCH, CHANNEL_SUFFIX_MISMATCH, GRAY_NOT_ALLOWED_ON_CRITICAL, or INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or CHANNEL_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "VERSION_ALREADY_EXISTS, CHANNEL_CONFLICT, or VERSION_NOT_DRAFT"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upsert draft version idempotently",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/artifacts/bundle": {
      "post": {
        "description": "Uploads a multi-architecture bundle archive for an existing draft version.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Unique idempotency key preventing duplicate processing within 24 hours.",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When 'true' or '1', publish after unpacking (default false).",
            "in": "query",
            "name": "publish",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/zip": {
              "schema": {
                "description": "Raw binary zip stream.",
                "format": "binary",
                "type": "string"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "archive": {
                    "description": "Alias of file.",
                    "format": "binary",
                    "type": "string"
                  },
                  "bundle": {
                    "description": "Alias of file.",
                    "format": "binary",
                    "type": "string"
                  },
                  "file": {
                    "description": "Bundle zip archive file.",
                    "format": "binary",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Bundle archive file (multipart/form-data or application/zip stream).",
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CIReleasesOutput"
                }
              }
            },
            "description": "Bundle accepted for asynchronous unpacking; poll GET /api/v1/admin/jobs/{job_id}."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or ZIP_LAYOUT_INVALID"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload bundle archive for existing version",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/artifacts/delta": {
      "post": {
        "description": "Requests asynchronous binary delta patch generation between two versions (source version in request body, target version in path; C10-7, §7.2).",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Unique idempotency key preventing duplicate processing within 24 hours.",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "algo": {
                    "description": "Defaults to platform matrix delta_algo, then hdiffpatch",
                    "enum": [
                      "hdiffpatch",
                      "bsdiff",
                      "xdelta3"
                    ],
                    "type": "string"
                  },
                  "arch": {
                    "type": "string"
                  },
                  "hw_rev": {
                    "description": "Optional hardware revision variant",
                    "type": "string"
                  },
                  "os": {
                    "type": "string"
                  },
                  "source_version": {
                    "description": "Source version ref (integer or semver); target = path version",
                    "type": "string"
                  }
                },
                "required": [
                  "source_version",
                  "os",
                  "arch"
                ],
                "type": "object"
              }
            }
          },
          "description": "Parameters for on-demand binary delta generation.",
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "created": {
                      "description": "false when an Idempotency-Key duplicate was returned",
                      "type": "boolean"
                    },
                    "engines": {
                      "description": "Per-algo engine availability snapshot",
                      "items": {
                        "properties": {
                          "algo": {
                            "type": "string"
                          },
                          "implementation": {
                            "enum": [
                              "cgo",
                              "pure-go"
                            ],
                            "type": "string"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "job_id": {
                      "format": "uuid",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Accepted; delta_generate job queued"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "DELTA_ALGO_UNSUPPORTED (unknown algo), DELTA_SAME_VERSION (source == target), INVALID_REQUEST"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "VERSION_NOT_FOUND / VERSION_LINE_NOT_FOUND / ARTIFACT_NOT_FOUND (missing full artifact)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request binary delta generation between published versions (C10-7, §7.2)",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/artifacts/reuse": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Creates new Artifact rows on the target (os,arch[,hw]) line referencing the SAME storage object (zero byte copy). Single-file: one new row with a file name recomputed for the target version. Multi-file: clones manifest entries plus a new full-archive row referencing the same pre-generated zip object; root_hash is recomputed (identical content gives the identical hash). Source must exist and its version must not be revoked. sha256 references must hit exactly one kind=full artifact in the project.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "arch": {
                    "type": "string"
                  },
                  "hw_rev": {
                    "type": "string"
                  },
                  "os": {
                    "type": "string"
                  },
                  "source": {
                    "properties": {
                      "artifact_id": {
                        "format": "uuid",
                        "type": "string"
                      },
                      "sha256": {
                        "type": "string"
                      }
                    },
                    "type": "object"
                  }
                },
                "required": [
                  "os",
                  "arch",
                  "source"
                ],
                "type": "object"
              }
            }
          },
          "description": "Storage object reference for zero-copy artifact reuse.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "artifacts": {
                      "items": {
                        "$ref": "#/components/schemas/Artifact"
                      },
                      "type": "array"
                    },
                    "manifest": {
                      "$ref": "#/components/schemas/ManifestResult"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Reference rows created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or AMBIGUOUS_SHA256 (multiple matches, use artifact_id)"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND, VERSION_NOT_FOUND or ARTIFACT_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "ARTIFACT_IMMUTABLE, VERSION_REVOKED (revoked source) or PACKAGE_TYPE_IMMUTABLE (single/multi mismatch)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reuse an existing storage object as this version's artifact (C14-1)",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/deprecate": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Transition published to deprecated.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_STATE_TRANSITION"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Deprecate version",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/exists": {
      "get": {
        "description": "Always returns HTTP 200 with exists boolean (never 404 for missing version).",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionExists"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check version existence",
        "tags": [
          "Versions"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/gray": {
      "get": {
        "description": "Runs lazy admission then returns knobs and coverage KPIs.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrayStatus"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get incremental gray status",
        "tags": [
          "Gray"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Updates start/step/interval without resetting gray_started_at. Critical versions cannot set start < 100.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrayPatchInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrayStatus"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Patch gray knobs",
        "tags": [
          "Gray"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/gray/allowlist": {
      "delete": {
        "description": "Removes client device identifiers from the version-level gray rollout allowlist.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrayAllowlistWriteInput"
              }
            }
          },
          "description": "Namebook UUIDs to remove.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrayAllowlistDeleteOutput"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST (missing client_ids)"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove gray allowlist entries (idempotent)",
        "tags": [
          "Gray"
        ]
      },
      "get": {
        "description": "Lists version-level gray allowlist rows (stored device_hash, source, created_at).",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrayAllowlistList"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List gray allowlist entries",
        "tags": [
          "Gray"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Enrolls registered clients into the version-level gray allowlist by client_ids.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrayAllowlistWriteInput"
              }
            }
          },
          "description": "Namebook UUIDs to add.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrayAllowlistList"
                }
              }
            },
            "description": "OK (deduplicated, stored form echoed)"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST (missing client_ids or device_id_policy=none)"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add gray allowlist entries",
        "tags": [
          "Gray"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/gray/clients": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrayClientsOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List gray allowlisted clients",
        "tags": [
          "Gray"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/gray/complete": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Marks the version as full push. Anonymous check and public feeds can then see it.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrayStatus"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Complete gray immediately",
        "tags": [
          "Gray"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/gray/series": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GraySeriesOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Gray coverage time series",
        "tags": [
          "Gray"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ]
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/line-defaults": {
      "get": {
        "description": "Returns min_os and min_api_level from the highest compare-key version strictly below {version} that has the requested os/arch line. 200 with nulls if none.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "Current version being edited.",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LineDefaultsOutput"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Prefill line min_os and min_api_level",
        "tags": [
          "Line Defaults"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines": {
      "get": {
        "description": "Lists platform slices for this version, each with artifacts[] (size, sha256, kind, file_name).",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionLineListOutput"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform slices for version",
        "tags": [
          "Versions"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Declares a new platform slice under a draft version.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VersionLineCreateInput"
              }
            }
          },
          "description": "Platform slice declaration parameters."
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionLine"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST (os/arch not on project matrix when matrix is non-empty)"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND, VERSION_NOT_FOUND, or MATRIX_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "VERSION_LINE_ALREADY_EXISTS or VERSION_NOT_DRAFT"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create platform slice on draft version",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}": {
      "get": {
        "description": "Retrieves details and processing status for a specific platform slice.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionLine"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND, VERSION_NOT_FOUND, or VERSION_LINE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get platform slice details",
        "tags": [
          "Versions"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target operating system slug (windows, linux, macos, android).",
          "in": "path",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target CPU architecture slug (x86_64, arm64, x86).",
          "in": "path",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "description": "Updates platform-specific gray rollout percentage override or platform notes.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LineRolloutPatchInput"
              }
            }
          },
          "description": "Per-line gray rollout override parameters.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionLine"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND, VERSION_NOT_FOUND, or VERSION_LINE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Patch per-line gray rollout override",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/artifacts": {
      "post": {
        "description": "Uploads a binary artifact for the specified platform line (POST method). Supports multipart form or raw octet-stream.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target operating system (e.g. windows, linux, macos, android).",
            "in": "path",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target CPU architecture (e.g. x86_64, arm64, x86).",
            "in": "path",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Stable artifact file name.",
            "in": "query",
            "name": "filename",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Hardware revision variant slug.",
            "in": "query",
            "name": "hw_rev",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Hex-encoded SHA-256 checksum declared in request header for server-side integrity verification.",
            "in": "header",
            "name": "X-Content-SHA256",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Unique idempotency key preventing duplicate processing within 24 hours.",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "description": "Raw binary file bytes.",
                "format": "binary",
                "type": "string"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "description": "Artifact binary file.",
                    "format": "binary",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Binary artifact payload.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Artifact"
                }
              }
            },
            "description": "Artifact uploaded and registered successfully."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "CHECKSUM_MISMATCH / HW_REV_UNKNOWN"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "ARTIFACT_IMMUTABLE"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload artifact (multipart/form-data or raw stream)",
        "tags": [
          "Artifacts"
        ]
      },
      "put": {
        "description": "Uploads a binary artifact for the specified platform line (PUT method). Supports multipart form or raw octet-stream.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target operating system (e.g. windows, linux, macos, android).",
            "in": "path",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target CPU architecture (e.g. x86_64, arm64, x86).",
            "in": "path",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Stable artifact file name.",
            "in": "query",
            "name": "filename",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Hardware revision variant slug.",
            "in": "query",
            "name": "hw_rev",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Minimum hardware revision required for this artifact variant.",
            "in": "query",
            "name": "min_hw_rev",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Maximum hardware revision compatible with this artifact variant.",
            "in": "query",
            "name": "max_hw_rev",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated list of explicitly compatible hardware revisions.",
            "in": "query",
            "name": "compatible_hw_revs",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Detached cryptographic signature over the artifact file payload.",
            "in": "query",
            "name": "artifact_signature",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Hex-encoded SHA-256 checksum declared in request header for server-side integrity verification.",
            "in": "header",
            "name": "X-Content-SHA256",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Unique idempotency key preventing duplicate processing within 24 hours.",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "description": "Raw binary file bytes.",
                "format": "binary",
                "type": "string"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "description": "Artifact binary file.",
                    "format": "binary",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Binary artifact payload.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Artifact"
                }
              }
            },
            "description": "Artifact uploaded and registered successfully."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "CHECKSUM_MISMATCH / HW_REV_UNKNOWN"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "ARTIFACT_IMMUTABLE"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload artifact (small file or raw stream)",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/artifacts/presign": {
      "post": {
        "description": "Generates an S3 presigned PUT URL or direct API relay URL for client-side direct upload.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target operating system (e.g. windows, linux, macos, android).",
            "in": "path",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target CPU architecture (e.g. x86_64, arm64, x86).",
            "in": "path",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadArtifactInput"
              }
            }
          },
          "description": "Optional artifact metadata (filename, size, expected sha256).",
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PresignUploadOutput"
                }
              }
            },
            "description": "Presigned upload URL generated successfully."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Generate presigned direct upload URL or API proxy URL",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/artifacts/tus": {
      "post": {
        "description": "Initializes a resumable TUS 1.0 upload session for large artifact files (C05-4).",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target operating system (e.g. windows, linux, macos, android).",
            "in": "path",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target CPU architecture (e.g. x86_64, arm64, x86).",
            "in": "path",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Total declared file byte length for TUS 1.0 upload session.",
            "in": "header",
            "name": "Upload-Length",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Base64-encoded key-value metadata for TUS 1.0 upload session.",
            "in": "header",
            "name": "Upload-Metadata",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "TUS protocol specification version (1.0.0).",
            "in": "header",
            "name": "Tus-Resumable",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Unique idempotency key preventing duplicate processing within 24 hours.",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Total size of the file to be uploaded in bytes.",
            "in": "header",
            "name": "Upload-Length",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Base64-encoded key-value metadata (filename, sha256, hw_rev).",
            "in": "header",
            "name": "Upload-Metadata",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Total size of the file to be uploaded in bytes.",
            "in": "header",
            "name": "Upload-Length",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Base64-encoded key-value metadata (filename, sha256, hw_rev).",
            "in": "header",
            "name": "Upload-Metadata",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Total size of the file to be uploaded in bytes.",
            "in": "header",
            "name": "Upload-Length",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Base64-encoded key-value metadata (filename, sha256, hw_rev).",
            "in": "header",
            "name": "Upload-Metadata",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "TUS session created; returns Location header with upload URL.",
            "headers": {
              "Location": {
                "description": "URL of the created upload resource.",
                "schema": {
                  "type": "string"
                }
              },
              "Tus-Resumable": {
                "description": "TUS protocol version (1.0.0).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST / HW_REV_UNKNOWN"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "ARTIFACT_IMMUTABLE"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Initialize TUS 1.0 upload session",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/build-archive": {
      "post": {
        "description": "Builds or uploads a pre-packaged full archive zip for a multi-file version line (C06-4).",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target operating system (e.g. windows, linux, macos, android).",
            "in": "path",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target CPU architecture (e.g. x86_64, arm64, x86).",
            "in": "path",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/zip": {
              "schema": {
                "description": "Raw binary zip stream.",
                "format": "binary",
                "type": "string"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "description": "Zip package archive.",
                    "format": "binary",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Full package zip archive (multipart or binary stream).",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Artifact"
                }
              }
            },
            "description": "Full archive registered successfully."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_PATH or ZIP_MANIFEST_MISMATCH"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_LINE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Build or upload full archive zip for multi-file version line",
        "tags": [
          "Artifacts"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/disable": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target operating system slug (windows, linux, macos, android).",
          "in": "path",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target CPU architecture slug (x86_64, arm64, x86).",
          "in": "path",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Disables a platform slice, preventing client updates.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionLine"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND, VERSION_NOT_FOUND, or VERSION_LINE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Disable platform slice",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/manifest": {
      "get": {
        "description": "Retrieves the multi-file manifest entries and root hash for a version line.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target operating system (e.g. windows, linux, macos, android).",
            "in": "path",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target CPU architecture (e.g. x86_64, arm64, x86).",
            "in": "path",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestResult"
                }
              }
            },
            "description": "Manifest entries and root hash"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_LINE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get manifest for version line",
        "tags": [
          "Manifest"
        ]
      },
      "put": {
        "description": "Submits or updates multi-file manifest entries and recalculates the root hash.",
        "parameters": [
          {
            "description": "Project UUID, active slug, or retained slug alias.",
            "in": "path",
            "name": "project_ref",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Version identifier (SemVer 2.0 or integer build number).",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target operating system (e.g. windows, linux, macos, android).",
            "in": "path",
            "name": "os",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Target CPU architecture (e.g. x86_64, arm64, x86).",
            "in": "path",
            "name": "arch",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PutManifestRequest"
              }
            }
          },
          "description": "Multi-file manifest entry records.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestResult"
                }
              }
            },
            "description": "Updated manifest and calculated root hash"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_PATH or CHECKSUM_MISMATCH"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_LINE_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "VERSION_IMMUTABLE"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Set manifest entries for version line",
        "tags": [
          "Manifest"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/ready": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target operating system slug (windows, linux, macos, android).",
          "in": "path",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target CPU architecture slug (x86_64, arm64, x86).",
          "in": "path",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Marks a platform slice as ready for release publication.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionLine"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND, VERSION_NOT_FOUND, or VERSION_LINE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Mark platform slice as ready",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/lines/{os}/{arch}/yank": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target operating system slug (windows, linux, macos, android).",
          "in": "path",
          "name": "os",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "description": "Target CPU architecture slug (x86_64, arm64, x86).",
          "in": "path",
          "name": "arch",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Yanks a platform slice, removing it from update visibility while permitting downgrade.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionLine"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND, VERSION_NOT_FOUND, or VERSION_LINE_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Yank platform slice",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/promote": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Only published versions. If the SemVer suffix rule allows, Version.channel is updated in place; a suffix conflict returns 400 CHANNEL_SUFFIX_MISMATCH with a remedy hint (create a new version with a higher compare key and reuse artifacts). A published version with the same compare key on the target channel returns 409 CHANNEL_CONFLICT. Artifact rows are not moved.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "target_channel": {
                    "type": "string"
                  }
                },
                "required": [
                  "target_channel"
                ],
                "type": "object"
              }
            }
          },
          "description": "Channel promotion parameters.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "Promoted version (same publicVersion shape as GET)."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_REQUEST or CHANNEL_SUFFIX_MISMATCH (details.remedy hints create-new-version + artifacts/reuse)"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "CHANNEL_CONFLICT or INVALID_TRANSITION"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Promote version to another channel (C14-2)",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/publish": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Transition draft to published. Requires at least one ready version line (ARTIFACT_REQUIRED).",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "ARTIFACT_REQUIRED or INVALID_STATE_TRANSITION"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Publish version",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/versions/{version}/revoke": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectRef"
        },
        {
          "description": "Release version string (SemVer 2.0 format or integer build number).",
          "in": "path",
          "name": "version",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "description": "Transition published or deprecated to revoked.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND or VERSION_NOT_FOUND"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_STATE_TRANSITION"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke version",
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/v1/admin/projects/{project_ref}/webhook/deliveries": {
      "get": {
        "description": "Queries recent webhook delivery attempts for release events with response codes and retry states.",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectRef"
          },
          {
            "description": "ID of the last delivery of the previous page",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "description": "Maximum number of records to return per page.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryListOutput"
                }
              }
            },
            "description": "List of webhook delivery attempts."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "UNAUTHORIZED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "FORBIDDEN"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "PROJECT_NOT_FOUND"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List publish webhook deliveries (C14-4)",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/api/v1/health": {
      "get": {
        "description": "Always HTTP 200 while the process is alive. ready is true only when PostgreSQL Ping and object-storage Head of the probe key both succeed. Unready does not change the status code.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusOutput"
                }
              }
            },
            "description": "Process is alive. ready reports database and object storage."
          }
        },
        "summary": "Liveness and readiness probe",
        "tags": [
          "System"
        ]
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "description": "Returns the complete OpenAPI 3.0 specification document in JSON format.",
        "responses": {
          "200": {
            "description": "OpenAPI JSON"
          }
        },
        "summary": "OpenAPI 3 document",
        "tags": [
          "System"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "This plane's HTTP listener (admin default :8081).",
      "url": "/"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Process probes (liveness plus ready) and this plane's OpenAPI document."
    },
    {
      "name": "Auth",
      "description": "Administrator login, logout, session, and 2FA (TOTP / passkey / recovery)."
    },
    {
      "name": "Admins",
      "description": "Instance administrator accounts. Platform admin only."
    },
    {
      "name": "Projects",
      "description": "Project CRUD, settings, project tokens, and CI tokens."
    },
    {
      "name": "Members",
      "description": "Project membership and roles."
    },
    {
      "name": "Channels",
      "description": "Release channels including system alpha/beta/stable."
    },
    {
      "name": "InstallPolicy",
      "description": "Project and channel path install-policy templates that seed new multi-file Manifests."
    },
    {
      "name": "Languages",
      "description": "Project language rows used by changelog and announcement editors."
    },
    {
      "name": "Platforms",
      "description": "Platform matrix, hardware revisions, and the platform catalog."
    },
    {
      "name": "Versions",
      "description": "Version lifecycle, version lines, publish / deprecate / revoke."
    },
    {
      "name": "Artifacts",
      "description": "Artifact metadata, uploads, bundles, and related jobs."
    },
    {
      "name": "Manifest",
      "description": "Per-line file manifest management."
    },
    {
      "name": "Gray",
      "description": "Gray rollout status and device allowlist."
    },
    {
      "name": "Clients",
      "description": "Registered devices as seen by operators (includes GeoIP)."
    },
    {
      "name": "Announcements",
      "description": "Announcement CRUD. Not embedded in check or feeds."
    },
    {
      "name": "Media",
      "description": "Markdown media upload and listing."
    },
    {
      "name": "Store Listings",
      "description": "Per-protocol store listings that back client-plane feeds."
    },
    {
      "name": "Webhooks",
      "description": "Outbound webhook deliveries."
    },
    {
      "name": "Audit",
      "description": "Project audit log."
    },
    {
      "name": "Line Defaults",
      "description": "Default version-line settings by platform."
    },
    {
      "name": "Jobs",
      "description": "Background jobs (delta, bundle, reuse)."
    },
    {
      "name": "Telemetry",
      "description": "Admin privacy wipe of device telemetry and matching gray-allowlist rows."
    },
    {
      "name": "GeoIP",
      "description": "GeoIP database files used to enrich admin client rows. Objects live on the private backend."
    },
    {
      "name": "Nodes",
      "description": "Cluster process identity and per-node artifact replica progress. Platform admin only."
    }
  ]
}