API Documentation

Programmatic access to Debian reproducibility verification data

Contents

Overview

All verification data is available in multiple machine-readable formats via static endpoints. These files are updated weekly via GitHub Actions and served through GitHub Pages.

Base URL: https://sheurich.github.io/debian-repro/

Update Frequency: Weekly (Sundays at 00:00 UTC) + manual triggers

Data Retention: Last 90 historical reports

Endpoints

GET Latest Verification Report (JSON)

https://sheurich.github.io/debian-repro/data/latest.json

Complete verification report including environment metadata, architecture results, and suite-level details.

Response Format

{
  "timestamp": "2025-11-07T12:00:00Z",
  "run_id": "1234567890",
  "serial": "20251020",
  "epoch": 1760918400,
  "environment": {
    "timestamp": "2025-11-07T12:00:00Z",
    "os": {
      "name": "Ubuntu",
      "version": "22.04",
      "kernel": "5.15.0",
      "arch": "x86_64"
    },
    "docker": "24.0.0",
    "qemu": "7.0.0",
    "git": {
      "version": "2.40.0",
      "sha": "d9b20d2...",
      "branch": "main"
    }
  },
  "architectures": {
    "amd64": {
      "status": "success",
      "suites": {
        "bookworm": {
          "reproducible": true,
          "sha256": "abc123...",
          "build_time_seconds": 456
        }
      }
    }
  }
}

GET Latest Verification Report (CSV)

https://sheurich.github.io/debian-repro/data/latest.csv

Flat table format for spreadsheet analysis and data science workflows.

Columns

Column Type Description
architecture string Architecture name (amd64, arm64, etc.)
suite string Debian suite name (bookworm, trixie, etc.)
reproducible boolean Whether the build was reproducible
sha256 string SHA256 checksum of rootfs tarball
build_time_seconds integer Build duration in seconds
timestamp ISO 8601 Verification timestamp
serial string Build serial (YYYYMMDD)

GET Latest Report (JSON-LD)

https://sheurich.github.io/debian-repro/data/latest.jsonld

Structured data using Schema.org vocabulary for semantic web applications and search engines.

Schema Types

  • Dataset - Verification data description
  • SoftwareApplication - Dashboard application metadata
  • PropertyValue - Metrics and measurements

GET Historical Verification Data (JSON)

https://sheurich.github.io/debian-repro/data/history.json

Array of verification reports (last 90 entries). Each entry has the same schema as latest.json.

Response Format

[
  {
    "timestamp": "2025-11-07T12:00:00Z",
    "run_id": "1234567890",
    "serial": "20251020",
    ...
  },
  {
    "timestamp": "2025-10-31T12:00:00Z",
    "run_id": "1234567889",
    "serial": "20251013",
    ...
  }
]

GET Historical Data (CSV)

https://sheurich.github.io/debian-repro/data/history.csv

Flat table with all historical verification results. Same columns as latest.csv.

GET Badge Endpoints

Shields.io compatible badge JSON endpoints for README badges.

Available Badges

  • badges/build-status.json - Overall build status (passing/failing)
  • badges/reproducibility-rate.json - Reproducibility percentage
  • badges/last-verified.json - Last verification date

Usage

https://img.shields.io/endpoint?url=https://sheurich.github.io/debian-repro/badges/reproducibility-rate.json

Data Schemas

Verification Report Schema

Field Type Required Description
timestamp ISO 8601 string Yes Report generation timestamp (UTC)
run_id string Yes CI run identifier
serial string Yes Build serial in YYYYMMDD format
epoch integer Yes SOURCE_DATE_EPOCH used for builds
environment object Yes Build environment metadata
architectures object Yes Map of architecture names to results

Architecture Result Schema

Field Type Required Description
status enum Yes success | failed | pending
suites object Yes Map of suite names to verification results

Suite Verification Schema

Field Type Required Description
reproducible boolean Yes Whether checksums matched
sha256 string Yes SHA256 checksum (64 hex chars)
official_sha256 string No Official checksum for comparison
build_time_seconds integer No Build duration in seconds

Usage Examples

Fetch Latest Report

curl -H "Accept: application/json" \
  https://sheurich.github.io/debian-repro/data/latest.json

Download CSV for Analysis

curl -o verification-data.csv \
  https://sheurich.github.io/debian-repro/data/latest.csv

Parse with jq

# Get reproducibility rate
curl -s https://sheurich.github.io/debian-repro/data/latest.json | \
  jq '[.architectures[].suites[] | select(.reproducible)] | length'

# List all reproducible suites for amd64
curl -s https://sheurich.github.io/debian-repro/data/latest.json | \
  jq '.architectures.amd64.suites | to_entries[] | select(.value.reproducible) | .key'

# Extract build times
curl -s https://sheurich.github.io/debian-repro/data/latest.json | \
  jq '.architectures[].suites[] | .build_time_seconds' | \
  awk '{sum+=$1; count++} END {print "Avg:", sum/count}'

Python Example

import requests
import pandas as pd

# Fetch JSON data
response = requests.get('https://sheurich.github.io/debian-repro/data/latest.json')
data = response.json()

# Or load CSV directly into pandas
df = pd.read_csv('https://sheurich.github.io/debian-repro/data/latest.csv')

# Calculate reproducibility rate
rate = df['reproducible'].sum() / len(df) * 100
print(f"Reproducibility rate: {rate:.1f}%")

JavaScript Example

// Fetch and parse JSON
fetch('https://sheurich.github.io/debian-repro/data/latest.json')
  .then(response => response.json())
  .then(data => {
    console.log('Serial:', data.serial);
    console.log('Architectures:', Object.keys(data.architectures));

    // Calculate stats
    let total = 0, reproducible = 0;
    Object.values(data.architectures).forEach(arch => {
      Object.values(arch.suites).forEach(suite => {
        total++;
        if (suite.reproducible) reproducible++;
      });
    });
    console.log(`Rate: ${(reproducible/total*100).toFixed(1)}%`);
  });

Rate Limits

All endpoints are served as static files via GitHub Pages. There are no explicit rate limits, but please be considerate:

Recommended: Check If-Modified-Since header to avoid unnecessary downloads.

Support

Questions or issues? Please open an issue on GitHub.

For CI/CD integration examples, see the workflows directory.