Agent Releases Domain

The Agent Releases domain provides access to published desktop agent releases and download redirects for release artifacts. Agent releases are shared platform data -- they are not scoped to a single client.

An agent release is identified by its version and includes the published artifacts for Windows and macOS. Artifact download actions are exposed as API-owned redirect URLs so the API contract remains stable even if the backing CDN, S3 layout, or signed URL strategy changes.

For embedding and endpoint design decisions, see the Design Guidelines.

Endpoints

Endpoint	Method	Description
List Agent Releases	GET	Paginated list of published agent releases
Get Latest Agent Release	GET	Fetch the current release for a release channel
Get Agent Release	GET	Fetch a single release directly by version
Download Agent Artifacts	GET	Redirect to the installer artifact for the latest release or a specific version

Why artifacts are embedded

Artifact metadata is embedded inside AgentRelease because it passes the embedding rule:

Relationship	Bounded?	Always needed?	Static?	Decision
AgentRelease → Windows artifact	Yes (0-1)	Yes	Yes	Embed
AgentRelease → macOS artifacts	Yes (0-2)	Yes	Yes	Embed

The release is the primary resource. The Windows and macOS artifacts are a small, fixed set of metadata and download actions that are always needed when viewing a release.

Why there is no Get Artifact endpoint

Artifacts do not have an independent identity outside their parent release. A dedicated artifact detail endpoint would return no additional data beyond what is already embedded in AgentRelease, so it is omitted.

Data Transfer Objects (DTOs)

AgentArtifact

Full artifact representation embedded inside AgentRelease.

{
  "filename": "ScalepadAgent-1.8.3.msi",
  "content_type": "application/octet-stream",
  "size_bytes": 12345678,
  "sha256": "abcdef1234567890",
  "download_url": "/v2/agent-releases/1.8.3/download?platform=windows"
}

Field	Type	Nullable	Description
filename	string	No	Published artifact filename
content_type	string	No	MIME type returned for the artifact
size_bytes	integer	Yes	Artifact size in bytes
sha256	string	Yes	SHA-256 checksum for the artifact
download_url	string	No	API-owned URL that redirects to the artifact

Source: agent release manifest entry for the artifact

Used in: AgentRelease.artifacts.windows, AgentRelease.artifacts.macos.arm64, AgentRelease.artifacts.macos.x86_64

---

AgentRelease

Full release representation returned by release-primary endpoints.

{
  "channel": "stable",
  "version": "1.8.3",
  "published_at": "2026-02-24T21:23:53.082Z",
  "notes_url": "https://github.com/Scalepad/scalepad-agent/releases/tag/v1.8.3",
  "artifacts": {
    "windows": {
      "filename": "ScalepadAgent-1.8.3.msi",
      "content_type": "application/octet-stream",
      "size_bytes": 12345678,
      "sha256": "abcdef1234567890",
      "download_url": "/v2/agent-releases/1.8.3/download?platform=windows"
    },
    "macos": {
      "arm64": {
        "filename": "ScalepadAgent-1.8.3.pkg",
        "content_type": "application/octet-stream",
        "size_bytes": 23456789,
        "sha256": "123456abcdef7890",
        "download_url": "/v2/agent-releases/1.8.3/download?platform=macos&arch=arm64"
      },
      "x86_64": {
        "filename": "ScalepadAgent-1.8.3.pkg",
        "content_type": "application/octet-stream",
        "size_bytes": 23456780,
        "sha256": "7890abcdef123456",
        "download_url": "/v2/agent-releases/1.8.3/download?platform=macos&arch=x86_64"
      }
    }
  }
}

Field	Type	Nullable	Description
channel	string	No	Release stream used to resolve this representation: stable, latest
version	string	No	Published release version
published_at	string (ISO 8601)	Yes	When the release was published
notes_url	string	Yes	Release notes URL
artifacts	object	No	Published release artifacts by platform
artifacts.windows	AgentArtifact	Yes	Windows MSI artifact
artifacts.macos	object	No	macOS PKG artifacts by architecture
artifacts.macos.arm64	AgentArtifact	Yes	macOS ARM64 PKG artifact
artifacts.macos.x86_64	AgentArtifact	Yes	macOS x86_64 PKG artifact

Source: agent release manifest and channel resolution metadata

Used in: List Agent Releases, Get Latest Agent Release, Get Agent Release