Fetch an artifact GitHub issue

The download endpoint on blockchain.puck.uno. Returns the actual bytes of a published artifact, after verifying them against the signed block.

vibecode
{"vibecode": {
    "doc": "blockchain_api_fetch",
    "role": "spec for the GET download endpoint on blockchain.puck.uno that returns artifact bytes (the actual file content) after server-side hash verification against the signed block",
    "endpoint": "GET /v1/download?url=<url-encoded-url>",
    "returns_on_success": "raw_artifact_bytes_with_artifacts_own_content_type",
    "returns_on_error": "empty_body_with_http_status_code_byte_oriented_endpoint_not_json",
    "verification": "server_fetches_artifact_hashes_bytes_compares_to_signed_artifact_hash"
}}

A simple GET request GitHub issue

Suppose someone wants to download the Caspian class at:

https://raw.githubusercontent.com/borg/classes/main/borg.casp

The client sends a GET to:

https://blockchain.puck.uno/v1/download?url=https%3A%2F%2Fraw.githubusercontent.com%2Fborg%2Fclasses%2Fmain%2Fborg.casp

If blockchain.puck.uno has a signed block for that URL AND the bytes still match the signed artifact_hash, the response (HTTP 200) returns the raw artifact bytes in the body, with the endorsement metadata and a cold-agent onboarding pointer in headers:

http
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 105
UNS: {"download.puck.uno": {"endorsement": { ...chain block, see endorsement.md... }}}
VIBECODE: {"spec": "https://puck.uno/", "skills": ["https://puck.uno/ai/skills/puck-basics"]}

class
    field 'designation', class: :string, required: true

    method &greet()
        'We are Borg.'
    end
end

(Standard noise like Date, Server, Connection, etc. omitted for clarity. On the wire, the UNS: and VIBECODE: JSON values are minified to a single line each; the example above is conceptually formatted for readability.)

The two custom headers:

A client that doesn't care about verification or onboarding can simply ignore both headers. The body is the file; everything else is metadata.

The content-type matches whatever the artifact actually is — .casp files are plain text, but binary artifacts (a font, an image, a compiled library) would carry their own content-type.

What the service does on a download GitHub issue

When the request comes in, blockchain.puck.uno:

  1. Looks up the signed block for the given URL.
  2. Fetches the artifact bytes from the artifact's URL (or a cached mirror).
  3. Hashes the bytes using the algorithm declared in the signed block (e.g., SHA-256).
  4. Compares the computed hash against the signed artifact_hash.
  5. If they match: returns the bytes to the client.
  6. If they don't match: refuses to serve (returns an error response — see below).

The hash check is what makes going through blockchain.puck.uno different from a direct fetch. A direct fetch from the artifact's URL gets the bytes whether they've been modified or not. This endpoint gets the bytes only if they still match what was signed.

Version selection GitHub issue

By default the endpoint returns the bytes signed under the most recent block for that URL. To pin a specific version:

GET /v1/download?url=<url>&semver=2.1.0

Returns the bytes signed under that exact semver.

GET /v1/download?url=<url>&at=2026-01-01

Returns the latest version signed on or before the given date.

These mirror the equivalent parameters on the endorsement endpoint. The UNS header on the response carries the endorsement metadata for whichever version was served.

Error responses GitHub issue

Unlike the endorsement endpoint and other JSON-returning endpoints, fetch is byte-oriented — success returns raw artifact bytes, errors return an empty body and rely on the HTTP status code to convey what went wrong. There's no JSON envelope here, no success boolean — the status code is the entire error signal.

Expected error cases:

The exact status code for some cases (e.g., is hash-mismatch a 409, a 410, or something else?) is TBD.

Open questions GitHub issue

See also GitHub issue

© 2026 Puck.uno